Add a table

In this tutorial you add a table of historical counter values and the time in which the counter reached those values. For the sake of simplicity, we will implement this in the increment function rather than use a storage hook.

Setup

Create a new MUD application from the template.

Modify the MUD configuration file

1. In an editor, open packages/contracts/mud.config.ts and add a table definition for History.

   mud.config.ts

   import { mudConfig } from "@latticexyz/world/register";
    
   export default mudConfig({
     tables: {
       Counter: {
         keySchema: {},
         schema: "uint32",
       },
       History: {
         keySchema: {
           counterValue: "uint32",
         },
         schema: {
           blockNumber: "uint256",
           time: "uint256",
         },
       },
     },
   });

2. Run this command in packages/contracts to regenerate the table libraries.

   pnpm build:mud

Update IncrementSystem

1. In an editor, open packages/contracts/src/systems/IncrementSystem.sol.

   • Modify the second import line to import History.
   • Modify the increment function to also update History. To see the exact functions that are available, you can look at packages/contracts/src/codegen/tables/History.sol (that is the reason we ran pnpm build:mud to recreate it already).

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0;
 
import { System } from "@latticexyz/world/src/System.sol";
import { Counter, History, HistoryData } from "../codegen/Tables.sol";
 
contract IncrementSystem is System {
  function increment() public returns (uint32) {
    uint32 counter = Counter.get();
    uint32 newValue = counter + 1;
    Counter.set(newValue);
    History.set(newValue, block.number, block.timestamp);
    return newValue;
  }
}

import { Counter, History, HistoryData } from "../codegen/Tables.sol";

struct HistoryData {
  uint256 blockNumber;
  uint256 time;
}

History.set(newValue, block.number, block.timestamp);

2. Run this command in packages/contracts to rebuild everything this package produces.

   pnpm build

Update the user interface

You can already run the application and see in the MUD Dev Tools that there is a :History table and it gets updates when you click Increment. Click the Store data tab and select the table :History.

However, you can also add the history to the user interface. The directions here apply to the vanilla client template, if you use anything else you'll need to modify them as appropriate.

1. Edit packages/client/src/index.ts.

   • Import two more functions we need.
   • In components.Counter.update$.subscribe, add code that updates the selection of history values.
   • Add a function that is called when the user selects a different option.
   index.ts

   import { setup } from "./mud/setup";
   import mudConfig from "contracts/mud.config";
   import { encodeEntity } from "@latticexyz/store-sync/recs";
   import { getComponentValueStrict } from "@latticexyz/recs";
    
   const {
     components,
     systemCalls: { increment },
     network,
   } = await setup();
    
   // Components expose a stream that triggers when the component is updated.
   components.Counter.update$.subscribe((update) => {
     const [nextValue, prevValue] = update.value;
     console.log("Counter updated", update, { nextValue, prevValue });
     document.getElementById("counter")!.innerHTML = String(nextValue?.value ?? "unset");
    
     let options: String = "";
     for (let i = 1; i <= nextValue?.value; i++) {
       options += `<option value="${i}">${i}</option>`;
     }
     document.getElementById("historyValue")!.innerHTML = options;
   });
    
   // Just for demonstration purposes: we create a global function that can be
   // called to invoke the Increment system contract via the world.
   // (See IncrementSystem.sol)
   (window as any).increment = async () => {
     console.log("new counter value:", await increment());
   };
    
   (window as any).readHistory = async (counterValue) => {
     const History = components.History;
     const entity = encodeEntity(History.metadata.keySchema, { counterValue });
     const { blockNumber, time } = getComponentValueStrict(History, entity);
     document.getElementById("blockNumber")!.innerHTML = blockNumber;
     document.getElementById("timeStamp")!.innerHTML = new Date(parseInt(Number(time) * 1000));
   };
    
   if (import.meta.env.DEV) {
     const { mount: mountDevTools } = await import("@latticexyz/dev-tools");
     mountDevTools({
       config: mudConfig,
       publicClient: network.publicClient,
       walletClient: network.walletClient,
       latestBlock$: network.latestBlock$,
       blockStorageOperations$: network.blockStorageOperations$,
       worldAddress: network.worldContract.address,
       worldAbi: network.worldContract.abi,
       write$: network.write$,
       recsWorld: network.world,
     });
   }

let options: String = "";

for (let i = 1; i <= nextValue?.value; i++) {
  options += `<option value="${i}">${i}</option>`;
}

document.getElementById("historyValue")!.innerHTML = options;

(window as any).readHistory = async counterValue => {
  const History = components.History
  const entity = encodeEntity(History.metadata.keySchema, { counterValue });

const { blockNumber, time } = getComponentValueStrict(History, entity);

document.getElementById("blockNumber")!.innerHTML = blockNumber;

  document.getElementById("timeStamp")!.innerHTML =
    new Date(parseInt(Number(time) * 1000))
}

2. Edit packages/clients/index.html.

   index.html

   <!DOCTYPE html>
   <html lang="en">
     <head>
       <meta charset="UTF-8" />
       <meta name="viewport" content="width=device-width, initial-scale=1.0" />
       <title>a minimal MUD client</title>
     </head>
     <body>
       <script type="module" src="/src/index.ts"></script>
       <div>Counter: <span id="counter">0</span></div>
       <button onclick="window.increment()">Increment</button>
       <hr />
       <h2>
         History for value:
         <select id="historyValue" onInput="window.readHistory(value)"></select>
       </h2>
       <table border>
         <tr>
           <th>Block number</th>
           <th>Time</th>
         </tr>
         <tr>
           <td id="blockNumber"></td>
           <td id="timeStamp"></td>
         </tr>
       </table>
     </body>
   </html>

<hr />
<h2>
  History for value:
  <select id="historyValue" onInput="window.readHistory(value)"></select>
</h2>

<table border></table>

<tr>
  <th>Block number</th>
  <th>Time</th>
</tr>
<tr>
  <td id="blockNumber"></td>
  <td id="timeStamp"></td>
</tr>

3. Run pnpm dev in the application's root directory, browse to the app URL, and click Increment a few times. Then select a counter value and see that the block number and correct time are written to the HTML table.