Keys with Value module

The KeysWithValue module (opens in a new tab) tracks a reverse mapping for a table that maps a value hash to a list of keys with this value. This is useful if you need the ability to lookup keys based on the data onchain.

💰

Using this module will add gas overhead to every write in the table it's used with. You can reduce this overhead by implementing your own "onchain index" pattern.

Deployment

It can be deployed multiple times, each time for a different table. For example, here is the forge script to deploy it for the Tasks table in the React template (opens in a new tab).

DeployKeyWithValueModule.s.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.21;
 
import { Script } from "forge-std/Script.sol";
import { console } from "forge-std/console.sol";
 
import { IWorld } from "../src/codegen/world/IWorld.sol";
import { WorldResourceIdLib, WorldResourceIdInstance } from "@latticexyz/world/src/WorldResourceId.sol";
import { RESOURCE_TABLE } from "@latticexyz/world/src/worldResourceTypes.sol";
import { ResourceId } from "@latticexyz/store/src/ResourceId.sol";
import { KeysWithValueModule } from "@latticexyz/world-modules/src/modules/keyswithvalue/KeysWithValueModule.sol";
 
contract DeployKeyWithValueModule is Script {
  function run() external {
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
    address worldAddress = 0xC14fBdb7808D9e2a37c1a45b635C8C3fF64a1cc1;
 
    vm.startBroadcast(deployerPrivateKey);
    IWorld world = IWorld(worldAddress);
 
    // Deploy the module
    KeysWithValueModule keysWithValueModule = new KeysWithValueModule();
    ResourceId sourceTableId = WorldResourceIdLib.encode({ typeId: RESOURCE_TABLE, namespace: "", name: "Tasks" });
    world.installRootModule(keysWithValueModule, abi.encode(sourceTableId));
 
    vm.stopBroadcast();
  }
}

Explanation

    KeysWithValueModule keysWithValueModule = new KeysWithValueModule();

Deploy the module. Modules are stateless, so if there is already a copy of the contract on the blockchain you can just use that.

    ResourceId sourceTableId =
       WorldResourceIdLib.encode({ typeId: RESOURCE_TABLE, namespace: "", name: "Tasks" });

Get the resourceID for the table that needs a reverse index.

    world.installRootModule(keysWithValueModule, abi.encode(sourceTableId));

Actually install the module in the World. At present it is a root module to ensure it can specify a hook on the relevant table. In the future we might add a feature to allow it to be in a namespace.

Usage

Installing the module creates a table called keywval__<table name>. When entries are added or modified in the source table, a hash of their values gets written to this table as a key, with the relevant key as the value. This only applies from the time the module is installed, entries created prior to that don't get the reverse mapping.

To get the keys you use getKeysWithValue (opens in a new tab) with these parameters:

The identifier of the source table
The encoded static fields (the result of <table name>.encodeStatic)
The encoded lengths of the dynamic fields (the result of <table name>.encodeLengths)
The encoded dynamic fields themselves (the result of <table name>.encodeDynamic)

For example, here is the forge script to add a task to Tasks in the React template (opens in a new tab) and then find the key from the data.

UseKeysWithValues.s.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.21;
 
import { Script } from "forge-std/Script.sol";
import { console } from "forge-std/console.sol";
import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol";
 
import { IWorld } from "../src/codegen/world/IWorld.sol";
import { getKeysWithValue } from "@latticexyz/world-modules/src/modules/keyswithvalue/getKeysWithValue.sol";
import { Tasks } from "../src/codegen/index.sol";
 
import { EncodedLengths, EncodedLengthsLib } from "@latticexyz/store/src/EncodedLengths.sol";
 
contract UseKeysWithValues is Script {
  function run() external {
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
    address worldAddress = 0xC14fBdb7808D9e2a37c1a45b635C8C3fF64a1cc1;
 
    uint createdAt = block.timestamp;
    uint completedAt = 0;
    string memory description = "Test";
 
    vm.startBroadcast(deployerPrivateKey);
    IWorld(worldAddress).addTask(description);
    vm.stopBroadcast();
 
    StoreSwitch.setStoreAddress(worldAddress);
 
    bytes32[] memory keys = getKeysWithValue(
      Tasks._tableId,
      Tasks.encodeStatic(createdAt, completedAt),
      Tasks.encodeLengths(description),
      Tasks.encodeDynamic(description)
    );
 
    console.log("Number of keys:", keys.length);
    for (uint i = 0; i < keys.length; i++) {
      console.log("Key #", i, "is", uint256(keys[i]));
    }
  }
}

Explanation

import { Tasks } from "../src/codegen/index.sol";

It is easiest to use getKeysWithValue when you have the definition of the source table.

    vm.startBroadcast(deployerPrivateKey);
    IWorld(worldAddress).addTask(description);
    vm.stopBroadcast();

Create an entry with this description. The two static fields, createdAt and completedAt, are filled by TasksSystem.addTask (opens in a new tab).

    StoreSwitch.setStoreAddress(worldAddress);

To read from keywval__Tasks we need to set the store address to worldAddress.

    bytes32[] memory keys = getKeysWithValue(
        TasksTableId,
        Tasks.encodeStatic(createdAt,completedAt),
        Tasks.encodeLengths(description),
        Tasks.encodeDynamic(description)
    );

Actually get the key(s), using the encoded static fields, encoded lengths, and encoded dynamic fields.

Modules Keys in Table