DEV Community: Filosofía Código EN

How Local Storage Wallets on Ethereum Work

Ahmed Castro — Thu, 07 Aug 2025 20:07:27 +0000

You need wallets in order to interact with decentralized apps on Ethereum, also called dApps. It holds your private key, signs your transactions, and proves your identity on-chain. Most people are familiar with browser extensions or mobile apps like MetaMask or Rabby. But there's another approach, local storage wallets, that provides more speed and better user experience.

This article explains what a local storage wallet is, how it works, and what it means for your experience on platforms like realtimeplay.xyz, a 100% on-chain casino with ultra-fast experience on MegaETH.

What Is a Local Storage Wallet?

A local storage wallet is a lightweight Ethereum wallet created and stored directly in your browser’s local storage, this is the same technology your browser uses to remember things like website settings or form data. This means the wallet is:

Created automatically by your browser.
Stored only on your device, never on a server.
Ready to use immediately, without needing to install anything.

In technical terms, it's just a key pair (a public Ethereum address and a private signing key) stored securely in the browser using JavaScript APIs like window.localStorage.

Why Use a Local Storage Wallet?

Traditional wallets are great for managing multiple assets and interacting across the Ethereum ecosystem. But they're not always ideal when you're trying to:

Create a quick wallet for fast onboarding.
Interact with a dApp that needs sub-second feedback.
Avoid the overhead of external wallet prompts or popups.

With a local storage wallet:

There’s no extension to install.
No user approval needed for every transaction.
The experience is immediate, perfect for games that need to feel instant and fluid.

This is especially important in environments like MegaETH, where every action is an on-chain transaction and execution happens in milliseconds.

Is It Safe?

Local storage wallets give you full control and that includes responsibility.

You own the keys. No one else, not even the dApp, can access them.
But they’re stored in your browser, so clearing your cache or using incognito mode could mean losing access unless you back it up.

Many apps offer a “download backup” or “export wallet” option. If you plan to use your wallet regularly, make sure to back it up securely.

How Does It Work on realtimeplay.xyz?

When you visit realtimeplay.xyz, a local storage wallet is generated for you automatically (if you don’t already have one). This wallet lets you:

Instantly start playing without installing anything.
Sign and send transactions directly to the chain.
Enjoy a casino experience that feels like a Web2 app but is fully on-chain.

You can also export your wallet if you ever want to import it into another Ethereum wallet app or manage it yourself.

What Happens If I Refresh or Close My Browser?

As long as you’re not in incognito mode and haven’t cleared your browser data, your wallet will persist. The next time you open the site, the same wallet is ready to use.

But again, if you clear your local storage, the wallet is gone along with access to any funds or progress. Always back it up if you care about keeping it.

How to Create a Secure Telegram Bot🔒 with EIP-712

Ahmed Castro — Sun, 20 Jul 2025 17:16:54 +0000

Telegram has around one billion active users per month and is a very important part of dApps and Web3 interfaces and communities. However, many Telegram bots still use insecure interaction methods.

By completing this guide, you’ll learn a better way to connect users to decentralized applications via Telegram. This tutorial shows how to authenticate Telegram users using their Web3 wallets, without ever accessing their private keys.

In this tutorial you’ll learn how to:

Create a secure Telegram bot: Build a bot that authenticates users via Web3 wallet signatures without storing private keys.
Implement ERC-712 signatures: Create an authentication flow where the user signs human-readable messages.
Enable flexible authentication: Users can interact with any type of application via Telegram, from secret groups to DeFi transactions or airdrops.

To see the full project, check out the complete code.

Application flow.

1. Create a New Telegram Bot

Creating a Telegram bot is very simple. Just send a direct message to the Telegram account @BotFather. Send the command /newbot, follow the instructions, and you’ll receive a token that we’ll use to interact with the Telegram library in the next step.

Send /newbot to @botfather to create a new Telegram bot.

2. Launch the Telegram Bot Backend

First, install the dependencies. Make sure you have Node.js installed, I recommend via nvm.

Once Node.js is installed, run:

npm install node-telegram-bot-api ethers dotenv express cors

Now, create a .env file with the following:

.env

BOT_TOKEN=your_telegram_bot_token
CHAIN_ID=1
WEB_DAPP_URL=http://localhost:3000

Edit the CHAIN_ID depending on the chain your dApp or community is. You can use Chainlist to figure out the chain id of the blockchain you're using. If your bot is chain agnostic use 1 as id, this is the Ethereum chain id.

Don’t forget to create a .gitignore file to avoid uploading .env to public repositories:

.gitignore

.env
node_modules

This is the bot.js file. It launches a bot that listens to Telegram messages and verifies wallet signatures. Telegram bots use polling to get messages locally, for production, consider using a webhook and hosting the server remotely.

For this tutorial, we’ll use polling. Learn more about webhooks in the Telegram Bot API docs.

When a user sends message with the authenticate text, the bot replies with a link to the web dApp. The dApp will sign a message and send it to the bot, which verifies the signature and welcomes the user.

// We'll use the official telegram bot library and ethers to verify the user's signature
const TelegramBot = require("node-telegram-bot-api");
const { ethers } = require("ethers");
require("dotenv").config();
const express = require("express");
const cors = require("cors");

const bot = new TelegramBot(process.env.BOT_TOKEN, { polling: true });
const CHAIN_ID = process.env.CHAIN_ID;
const WEB_DAPP_URL = process.env.WEB_DAPP_URL;

const app = express();
app.use(cors());
app.use(express.json());

// Initializes the Telegram bot 
(async () => {
    try {
        bot.botInfo = await bot.getMe();
        app.listen(8080, () => {
            console.log("\nServer is running on port 8080");
            console.log("Bot is running...");
        });
    } catch (error) {
        console.error(error);
        process.exit(1);
    }
})();

// The /verify enpoint is used to verify the signature and send a welcome message to the user
app.post("/verify", async (req, res) => {
    const { userId, message, signature } = req.body;
    try {
        const signerAddress = await getAuthenticationSigner(userId, message, signature);
        await bot.sendMessage(
            Number(userId), 
            `Welcome! You're authenticated as ${signerAddress}.\n\nEnjoy your welcome gift! 🎁`
        );
        res.json({ success: true, signerAddress });
    } catch (error) {
        console.error("Verification error:", error);
        res.status(400).json({ success: false, error: error.message });
    }
});

// getAuthenticationSigner returns the signer address
function getAuthenticationSigner(userId, message, signature) {
    // accessRequest es el esquema de datos real del mensaje que queremos verificar
    const accessRequest = {
        userId: userId,
        message: message,
    };
    // domain is your dApp general information, this should be the same for every message
    const domain = {
        name: "Telegram Group Access",
        version: "1",
        chainId: CHAIN_ID,
    };
    // types is your data schema, the structure of the data we want to verify
    const types = {
    AccessRequest: [
            { name: "userId", type: "uint256" },
            { name: "message", type: "string" },
        ]
    };
    // verifyTypedData check if the signature in the ERC-712 format and returns the signer address through ecrecover, this is done internally by the ethers library
    return ethers.verifyTypedData(domain, types, accessRequest, signature);
}

// This is the main function, it gets executed when the bot receives a message
bot.on("message", async (msg) => {
    const text = msg.text || "";
    // Verifica si el mensaje es "authenticate" y si es así, envía un mensaje al usuario para que visite el sitio web
    if (text.toLowerCase() === "authenticate") {
        // userId es el id del usuario en Telegram
        const userId = msg.from.id;
        // Enviamos el usuario a la dapp web para autenticarse
        bot.sendMessage(userId, `Please visit: ${WEB_DAPP_URL}?userId=${userId}`);
        return;
    }
});

console.log("\nBot is running...");

Run the bot:

node bot.js

Your bot is now running on http://127.0.0.1:8080.

Next, we’ll create the web dApp that interacts with it.

3. Create a Web dApp to Sign Messages

We’ll create 3 files:

index.html: The HTML page with the wallet connection and sign button
signature_messaging.js: Handles signing and sending the message
wallet_connection.js: Manages wallet connection

The dApp is a simple HTML page with a Sign button that opens the user’s wallet to sign a message.

Clicking the Sign button opens the ERC712 signature modal.

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
</head>
<body>
  <div>
    <!-- Connect Wallet button, only visible is wallet is not connected -->
    <input id="connect_button" type="button" value="Connect" onclick="connectWallet()" style="display: none"></input>
    <h1>Telegram Bot Authentication</h1>
    <p id="web3_message"></p>
    <h3>Sign Authentication Request</h3>
    <!-- This is the authentication button, will pop up the wallet signature modal -->
    <button type="button" id="sign" onclick="_signMessage()">Sign</button>
    <p id="signature"></p>
  </div>
    <!-- In this tutorial we'll use web3.js, you can have the same results with ethers.js or viem -->
  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/web3/1.3.5/web3.min.js"></script>
  <script type="text/javascript" src="wallet_connection.js"></script>
  <script type="text/javascript" src="signature_messaging.js"></script>
</body>

  <script>
    // The signMessage function is called when the user clicks the sign button
    function _signMessage()
    {
      const urlParams = new URLSearchParams(window.location.search);
      const userId = urlParams.get('userId');
      signMessage(userId, "I'm requesting access to the Telegram group.")
    }
  </script>
</html>

signature_messaging.js signs the message using the ERC712 standard and sends it to the bot backend via eth_signTypedData_v4.

signature_messaging.js

const BOT_API_URL = 'http://localhost:8080'
// Signs the message using the ERC-712 format
async function signMessage(userId, message)
{
  // ERC-712 expects you to send the message in a very specific format
  const msgParams = JSON.stringify({
    types: {
      EIP712Domain: [
        { name: 'name', type: 'string' },
        { name: 'version', type: 'string' },
        { name: 'chainId', type: 'uint256' },
      ],
      AccessRequest: [
        { name: 'userId', type: 'uint256' },
        { name: 'message', type: 'string' }
      ],
    },
    primaryType: 'AccessRequest',
    domain: {
      name: 'Telegram Group Access',
      version: '1',
      chainId: NETWORK_ID,
    },
    message: {
      userId: userId,
      message: message,
    },
  });

  // ERC-712 introduced the eth_signTypedData_v4 method, now is widely adopted by wallets
  const signature = await ethereum.request({
    method: "eth_signTypedData_v4",
    params: [accounts[0], msgParams],
  });

  document.getElementById("signature").textContent="Signature: " + signature;

  // Send the message to the telegram bot
  await sendSignature(userId, message, signature);
}

// Send the signature to the Telegram bot
async function sendSignature(userId, message, signature) {
  // We start by grouping the data to be sent to the bot
  const requestData = {
    userId: userId,
    message: message,
    signature: signature
  };

  try {
    // Now we send the data to the Telegram bot at the /verify POST endpoint
    // If all is correct, the bot will send a welcome message to the user
    const response = await fetch(BOT_API_URL + '/verify', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(requestData)
    });

    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    alert("Message sent successfully!");
  } catch (error) {
    console.error('Error:', error);
    alert("Failed to send message: " + error.message);
  }
}

Then, wallet_connection.js handles connecting to the wallet and updating the UI:

If you target a specific network id, edit NETWORK_ID.

wallet_connection.js

// Constants
const NETWORK_ID = 1
var accounts
var web3

// Automatically refreshes the browser if your wallet changes
function metamaskReloadCallback() {
  window.ethereum.on('accountsChanged', (accounts) => {
    document.getElementById("web3_message").textContent="Account changed, refreshing...";
    window.location.reload()
  })
  window.ethereum.on('networkChanged', (accounts) => {
    document.getElementById("web3_message").textContent="Network changed, refreshing...";
    window.location.reload()
  })
}

// Get a new Web3 instance
const getWeb3 = async () => {
  return new Promise((resolve, reject) => {
    if(document.readyState=="complete")
    {
      if (window.ethereum) {
        const web3 = new Web3(window.ethereum)
        window.location.reload()
        resolve(web3)
      } else {
        reject("must install MetaMask")
        document.getElementById("web3_message").textContent="Error: Please connect to MetaMask";
      }
    }else
    {
      window.addEventListener("load", async () => {
        if (window.ethereum) {
          const web3 = new Web3(window.ethereum)
          resolve(web3)
        } else {
          reject("must install MetaMask")
          document.getElementById("web3_message").textContent="Error: Please install Metamask";
        }
      });
    }
  });
};

// Loads the dApp and gets a Web3 object instance
async function loadDapp() {
  metamaskReloadCallback()
  document.getElementById("web3_message").textContent="Please connect to Metamask"
  var awaitWeb3 = async function () {
    web3 = await getWeb3()
    web3.eth.net.getId((err, netId) => {
      if (netId == NETWORK_ID) {
        var awaitContract = async function () {
          document.getElementById("web3_message").textContent="You are connected to Metamask"
          web3.eth.getAccounts(function(err, _accounts){
            accounts = _accounts
            if (err != null)
            {
              console.error("An error occurred: "+err)
            } else if (accounts.length > 0)
            {
              onWalletConnectedCallback()
              document.getElementById("account_address").style.display = "block"
            } else
            {
              document.getElementById("connect_button").style.display = "block"
            }
          });
        };
        awaitContract();
      } else {
        document.getElementById("web3_message").textContent="Please connect to Scroll";
      }
    });
  };
  awaitWeb3();
}

// Connect the user wallet
async function connectWallet() {
  await window.ethereum.request({ method: "eth_requestAccounts" })
  accounts = await web3.eth.getAccounts()
  onWalletConnectedCallback()
}

// Callbacked called when the user connected his wallet, you would typically read the user state on-chain here
const onWalletConnectedCallback = async () => {
}

// Starts the dApp
loadDapp()

Install a web server like lite-server:

npm install -g lite-server

Then, in the same directory as index.html:

lite-server

Your dApp is now running at http://127.0.0.1:3000.

4. Test Your Bot

Now let’s test it:

Send authenticate to the bot.
Visit the site the bot replies with, connect to Scroll Mainnet, and sign the message.
Check the bot’s reply in Telegram.

This flow securely authenticates users and enables actions on their behalf without storing private keys.

Next Steps

In this tutorial, we authenticated Telegram users via a Web3 wallet. We used the ERC712 standard and the eth_signTypedData_v4 method, and the Telegram API to send and receive messages.

In the next tutorial, we’ll use this authentication to control access to a Telegram group.

Thanks for reading this article!

Follow Filosofía Código on dev.to and in Youtube for everything related to Blockchain development.

One-click Loans on Aave with EIP-7702

Ahmed Castro — Sun, 20 Jul 2025 16:44:30 +0000

Historically, Ethereum has had a high barrier to entry with interfaces that are difficult to understand and use. In May 2025 Ethereum released EIP-7702, which is in my opinion, is the most significant improvement for user experience released on Ethereum. Thanks to it, an EOA, that is a regular Ethereum account, can temporarily become a smart contract.

Historically, taking out a loan on Aave takes three transactions. In this article we’ll see how to do it in a single transaction using EIP‑7702.

In this article we’ll show how to use EIP‑7702 to get a loan on Aave with one click. Aave is the largest collateralized lending platform on Ethereum, handling over $50 billion. Before this upgrade, borrowing required at least three transactions, whereas with EIP‑7702 we bundle those three actions into one.

Let’s start by understanding how Aave works, and then we’ll build step by step a frontend that does the entire process with a single button.

How to Get a Loan on Aave

Let's suppose you want $300 in WBTC by posting $1000 in DAI as collateral. To do this, you first have to approve the Aave contract to transfer your DAI via the approve function, then supply your DAI as collateral by calling supply, and finally borrow by calling borrow. From the user’s point of view this isn’t obvious, and until now we had no way to express it in a single transaction.

Example of an Aave position with a $300 WBTC loan backed by $1000 in DAI collateral.

In our example we’ll go through step by step how to do the same process with a single button. We’ll see how to enable EIP‑7702 in your wallet so that it can aggregate transactions, and then we’ll build a frontend to interact with Aave from your smart-contract wallet.

Temporarily Turn Your Wallet into a Smart Contract

With EIP‑7702 you can inject arbitrary code into your wallet. Another option, to save gas, is to have your wallet point to any other contract so that it “copies” the code at that address, we call this wallet delegation. In this example we’ll deploy and delegate to a Multicall7702 contract based on Multicall, a contract that batches multiple transactions but I adapted it for EIP‑7702 so it only allows the deployer to execute it. Otherwise your wallet would be exposed.

First, we’ll deploy the Multicall7702 contract and then point our wallet at that contract.

Wallet interfaces don’t yet support EIP‑7702, so for now we’ll use Foundry instead. Also, as dApp developers we shouldn’t worry about handling delegation in our interfaces. For security reasons, this should be implemented at the wallet level, not the dApp level.

Deploy the Multicall7702 Contract

Deploy the following contract on the network where you want to try this example and save the address. I’ll deploy it on Scroll Testnet, where you can connect via Chainlist and get funds from the faucet by messaging @scroll_up_sepolia_bot and then typing /drop 0xYOUR_WALLET_ADDRESS in the faucet chat.

If you deploy on another chain, I’ll explain the changes you need to make along the way.

The only change you must make before deploying the Multicall7702 contract is to replace 0xYOUR_EOA_ADDRESS with the wallet you want to convert:

// SPDX-License-Identifier: MIT
// Derived from MakerDAO’s Multicall3
// NOT AUDITED, DO NOT USE IN PRODUCTION
pragma solidity 0.8.12;

contract Multicall7702 {
    struct Call3Value { address target; bool allowFailure; uint256 value; bytes callData; }
    struct Result { bool success; bytes returnData; }

    address immutable public owner = 0xTU_DIRECCION_EOA;

    function aggregate3Value(Call3Value[] calldata calls) public payable returns (Result[] memory returnData) {
        require(owner == msg.sender, "Only owner"); // Prevent others from executing on your behalf
        uint256 valAccumulator;
        uint256 length = calls.length;
        returnData = new Result[](length);
        Call3Value calldata calli;
        for (uint256 i = 0; i < length;) {
            Result memory result = returnData[i];
            calli = calls[i];
            uint256 val = calli.value;
            unchecked { valAccumulator += val; }
            (result.success, result.returnData) = calli.target.call{value: val}(calli.callData);
            assembly {
                if iszero(or(calldataload(add(calli, 0x20)), mload(result))) {
                    mstore(0x00, 0x08c379a000000000000000000000000000000000000000000000000000000000)
                    mstore(0x04, 0x0000000000000000000000000000000000000000000000000000000000000020)
                    mstore(0x24, 0x0000000000000000000000000000000000000000000000000000000000000017)
                    mstore(0x44, 0x4d756c746963616c6c333a2063616c6c206661696c6564000000000000000000)
                    revert(0x00, 0x84)
                }
            }
            unchecked { ++i; }
        }
        require(msg.value == valAccumulator, "Multicall3: valor incorrecto");
    }
}

Delegate Your Wallet to Multicall7702

Install Foundry if you don’t have it:

curl -L https://foundry.paradigm.xyz | bash
foundryup

To delegate your wallet, run the following command—replacing YOUR_PRIVATE_KEY and 0xYOUR_CONTRACT_ADDRESS. If you’re on another chain, change the --rpc-url (you can get it from Chainlist):

cast send \
  --rpc-url https://scroll-public.scroll-testnet.quiknode.pro \
  --private-key YOUR_PRIVATE_KEY \
  --auth 0xYOUR_CONTRACT_ADDRESS $(cast az)

You can verify the delegation with:

cast code \
  --rpc-url https://scroll-public.scroll-testnet.quiknode.pro \
  0xYOUR_EOA_ADDRESS

You should see your Multicall7702 address in the form:

0xef0100YOUR_EOA_ADDRESS

Here 0xef0100 is the EIP‑7702 delegation prefix plus your contract address, meaning your wallet points to your Multicall7702 code.

Build the Frontend

Next, we’ll create a minimal frontend demo of EIP‑7702. All the code is commented so you can understand what’s needed for compatibility with this new standard.

In our dApp, the user will select how much WBTC to borrow backed by DAI. If you want to use other tokens, I’ll note the necessary changes.

We’ll build a very simple EIP‑7702–enabled dApp implementation.

We’ll use two files: index.html for the UI and blockchain_stuff.js for the logic. Place them side by side in a new folder.

index.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
</head>
<body>
  <input id="connect_button" type="button" value="Connect" onclick="connectWallet()" style="display: block"></input>
  <p id="account_address" style="display: none"></p>
  <p id="web3_message"></p>
  <p id="contract_state"></p>
  <label for="lending_token_amount">DAI supply amount:</label>
  <input type="input" value="" id="lending_token_amount" placeholder="e.g. 1000"></input>
  <br>
  <label for="borrowed_token_amount">WBTC borrow amount:</label>
  <input type="input" value="" id="borrowed_token_amount" placeholder="e.g. 0.005"></input>
  <br>
  <input type="button" value="One click loan" onclick="_oneClickLoan()"></input>
  <br>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/web3/1.3.5/web3.min.js"></script>
  <script src="blockchain_stuff.js"></script>
</body>
</html>

<script>
  function _oneClickLoan() {
    const lendingTokenAmount = document.getElementById("lending_token_amount").value;
    const borrowedTokenAmount = document.getElementById("borrowed_token_amount").value;
    oneClickLoan(lendingTokenAmount, borrowedTokenAmount);
  }
</script>

In the following file adjust NETWORK_ID, LENDING_ADDRESS, BORROWED_TOKEN, and AAVE_POOL_ADDRESS for your target chain and tokens.

blockchain_stuff.js

// Edit this if you want to change in other chain
const NETWORK_ID = 534351 // Scroll Sepolia

// Edit if you want to use other assets or other chain
const LENDING_ADDRESS = "0x7984e363c38b590bb4ca35aed5133ef2c6619c40" //Aave Testnet DAI en Scroll Sepolia
const BORROWED_TOKEN = "0x5ea79f3190ff37418d42f9b2618688494dbd9693" //Aave Testnet WBTC en Scroll Sepolia
const AAVE_POOL_ADDRESS = "0x48914C788295b5db23aF2b5F0B3BE775C4eA9440" // Aave Testnet Pool en Scroll Sepolia

// ABI we'll use, you should keep this in separate .json files to keep your code clean
const MULTICALL_ABI = [
  {
    "inputs": [
      {
        "components": [
          {"internalType": "address", "name": "target", "type": "address"},
          {"internalType": "bool", "name": "allowFailure", "type": "bool"},
          {"internalType": "uint256", "name": "value", "type": "uint256"},
          {"internalType": "bytes", "name": "callData", "type": "bytes"}
        ],
        "internalType": "struct Multicall3.Call3Value[]",
        "name": "calls",
        "type": "tuple[]"
      }
    ],
    "name": "aggregate3Value",
    "outputs": [
      {
        "components": [
          {"internalType": "bool", "name": "success", "type": "bool"},
          {"internalType": "bytes", "name": "returnData", "type": "bytes"}
        ],
        "internalType": "struct Multicall3.Result[]",
        "name": "returnData",
        "type": "tuple[]"
      }
    ],
    "stateMutability": "payable",
    "type": "function"
  }
];

const ERC20_ABI = [
  {
    "inputs": [
      {"internalType": "address", "name": "spender", "type": "address"},
      {"internalType": "uint256", "name": "value", "type": "uint256"}
    ],
    "name": "approve",
    "outputs": [
      {"internalType": "bool", "name": "", "type": "bool"}
    ],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [],
    "name": "decimals",
    "outputs": [
      {"internalType": "uint8", "name": "", "type": "uint8"}
    ],
    "stateMutability": "view",
    "type": "function"
  }
];

const AAVE_POOL_ABI = [
  {
    "inputs": [
      {"internalType": "address", "name": "asset", "type": "address"},
      {"internalType": "uint256", "name": "amount", "type": "uint256"},
      {"internalType": "address", "name": "onBehalfOf", "type": "address"},
      {"internalType": "uint16", "name": "referralCode", "type": "uint16"}
    ],
    "name": "supply",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      {"internalType": "address", "name": "asset", "type": "address"},
      {"internalType": "uint256", "name": "amount", "type": "uint256"},
      {"internalType": "uint256", "name": "interestRateMode", "type": "uint256"},
      {"internalType": "uint16", "name": "referralCode", "type": "uint16"},
      {"internalType": "address", "name": "onBehalfOf", "type": "address"}
    ],
    "name": "borrow",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  }
];

// Variables we will use
var lendingTokenContract
var borrowedTokenContract
var aavePoolContract
var myERC7702Account

var accounts
var web3

// Automatically reload when the user selects a new chain or uses another account
function metamaskReloadCallback() {
  window.ethereum.on('accountsChanged', (accounts) => {
    document.getElementById("web3_message").textContent="Se cambió el account, refrescando...";
    window.location.reload()
  })
  window.ethereum.on('networkChanged', (accounts) => {
    document.getElementById("web3_message").textContent="Se el network, refrescando...";
    window.location.reload()
  })
}

// Function to initalize Web3
const getWeb3 = async () => {
  return new Promise((resolve, reject) => {

    if(document.readyState=="complete")
    {
      if (window.ethereum) {
        const web3 = new Web3(window.ethereum)
        window.location.reload()
        resolve(web3)
      } else {
        reject("must install MetaMask")
        document.getElementById("web3_message").textContent="Error: Porfavor conéctate a Metamask";
      }
    }else
    {
      window.addEventListener("load", async () => {
        if (window.ethereum) {
          const web3 = new Web3(window.ethereum)
          resolve(web3)
        } else {
          reject("must install MetaMask")
          document.getElementById("web3_message").textContent="Error: Please install Metamask";
        }
      });
    }
  });
};

// Function to initalize the dApp, read the contracts and connects the wallet
async function loadDapp() {
  metamaskReloadCallback()
  document.getElementById("web3_message").textContent="Please connect to Metamask"
  var awaitWeb3 = async function () {
    web3 = await getWeb3()
    web3.eth.net.getId((err, netId) => {
      if (netId == NETWORK_ID) {
        var awaitContract = async function () {
          lendingTokenContract = new web3.eth.Contract(ERC20_ABI, LENDING_ADDRESS);
          borrowedTokenContract = new web3.eth.Contract(ERC20_ABI, BORROWED_TOKEN);
          aavePoolContract = new web3.eth.Contract(AAVE_POOL_ABI, AAVE_POOL_ADDRESS);

          document.getElementById("web3_message").textContent="You are connected to Metamask"
          onContractsInitCallback()
          web3.eth.getAccounts(function(err, _accounts){
            accounts = _accounts
            if (err != null)
            {
              console.error("An error occurred: "+err)
            } else if (accounts.length > 0)
            {
              onWalletConnectedCallback()
              document.getElementById("account_address").style.display = "block"
            } else
            {
              document.getElementById("connect_button").style.display = "block"
            }
          });
        };
        awaitContract();
      } else {
        document.getElementById("web3_message").textContent="Please connect to Goerli";
      }
    });
  };
  awaitWeb3();
}

async function connectWallet() {
  await window.ethereum.request({ method: "eth_requestAccounts" })
  accounts = await web3.eth.getAccounts()
  onWalletConnectedCallback()
}

loadDapp()

// Wallet executed when you change the accounts, this is a good place to read the on-chain state
const onContractsInitCallback = async () => {
}

// Callback called when the user connects the wallet, in this case we'll initalize smart account wallet
const onWalletConnectedCallback = async () => {
  myERC7702Account = new web3.eth.Contract(MULTICALL_ABI, accounts[0]);
}

// Function that is called from the frontend that receives the desired amount of collateral and borrow amounts
const oneClickLoan = async (lendingTokenAmount, borrowedTokenAmount) => {
    // Convert from ether to wei format depending on the amount of decimals of each token
    const scrDecimals = await lendingTokenContract.methods.decimals().call();
    const borrowedDecimals = await borrowedTokenContract.methods.decimals().call();
    const supplyAmount = Web3.utils.toBN(
        (parseFloat(lendingTokenAmount) * Math.pow(10, parseInt(scrDecimals))).toLocaleString('fullwide', {useGrouping:false})
    );
    const borrowAmount = Web3.utils.toBN(
        (parseFloat(borrowedTokenAmount) * Math.pow(10, parseInt(borrowedDecimals))).toLocaleString('fullwide', {useGrouping:false})
    );

    // We generate the contract calls encoded in a compatible way with our multicall contract
    const approveCall = lendingTokenContract.methods.approve(AAVE_POOL_ADDRESS, supplyAmount).encodeABI();
    const supplyCall = aavePoolContract.methods.supply(LENDING_ADDRESS, supplyAmount, accounts[0], 0).encodeABI();
    const interestRateMode = 2;
    const referralCode = 0;
    const borrowCall = aavePoolContract.methods.borrow(
        BORROWED_TOKEN,
        borrowAmount.toString(),
        interestRateMode,
        referralCode,
        accounts[0]
    ).encodeABI();

    const calls = [
        {
          target: LENDING_ADDRESS,
          allowFailure: false,
          value: 0,
          callData: approveCall
        },
        {
          target: AAVE_POOL_ADDRESS,
          allowFailure: false,
          value: 0,
          callData: supplyCall
        },
        {
          target: AAVE_POOL_ADDRESS,
          allowFailure: false,
          value: 0,
          callData: borrowCall
        }
      ];

      // We execute a call directed our ERC-7702 wallet
      const result = await myERC7702Account.methods.aggregate3Value(calls)
      .send({ from: accounts[0], gas: 0, value: 0 })
      .on('transactionHash', function(hash){
        document.getElementById("web3_message").textContent="Executing...";
      })
      .on('receipt', function(receipt){
        document.getElementById("web3_message").textContent="Success.";    })
      .catch((revertReason) => {
        console.log("ERROR! Transaction reverted: " + revertReason.receipt.transactionHash)
      });
}

Test Your dApp

Install Node.js if you don’t have it, I recommend via NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
nvm install 22
# Restart or reload your terminal

Install a web server:

npm i -g lite-server

Then start the frontend:

lite-server

Your web app will be at http://localhost:3000. Once you get your loan you can inspect the bundled transactions in detail on Etherscan and the Aave frontend.

In Etherscan you will be able to see how everything happened in a single transaction.

To continue learning about this and other new features made possible by this upgrade, see the EIP‑7702 Specification.

Thanks for reading this article!

Follow Filosofía Código on dev.to and in Youtube for everything related to Blockchain development.

Intro to Programatic Loans in Morpho

Ahmed Castro — Wed, 18 Jun 2025 18:30:12 +0000

From decentralized AI agents to automated DAO‑treasury management and advanced DeFi trading bots, programmable finance has been rising and offers many new possibilities. In this tutorial we’ll learn-by-doing one such use case: taking out a loan by interacting with Morpho v1 to borrow WETH against USDC on Base.

Throughout the guide you’ll learn not only how to deposit USDC and borrow WETH in a single transaction, but also how to repay your debt and retrieve your collateral. You’ll see how to parameterize your calls so that you can switch to any other Morpho market and add your own custom code.

Monolithic vs. Multi‑Market Lending

Major protocols like Aave and Compound adopt a monolithic architecture: a single, unified market pools liquidity across all assets. This yields deep reserves and stability but makes governance changes harder to adapt to the ever changing market conditions.

Aave offers a single market protocol-wide, while Morpho a multi-market approach.

Morpho instead provides a multi‑market framework. Each whitelisted organizations can create and update new markets, Morpho call this organizations "Curators" and users can select to enter on the market created by the Curators of their choice. Curators manage their own parameters: loan token, collateral token, interest‑rate module (IRM), oracle, collateralization ratio, etc. while Morpho itself supplies the infrastructure and matching engine. The result is flexible markets and more options for users, all accessed via a unified interface.

The Morpho API

Morpho exposes four core functions to manage collateralized loans:

supplyCollateral: Deposit collateral so you can borrow.
borrow: Draw loan assets up to your borrowing power.
repay: Return borrowed principal plus interest.
withdrawCollateral: Retrieve your collateral once you’ve repaid.

For simplicity, our contract will wrap supplyCollateral + borrow into a single borrowAgainstCollateral() call, and repay + withdrawCollateral into repayAndWithdraw().

Market parameters

Because Morpho supports multiple markets, every call requires a MarketParams struct:

struct MarketParams {
    address loanToken;
    address collateralToken;
    address oracle;
    address irm;
    uint256 lltv;
}

In this example we’ll target the WETH/USDC market on Base:

Parameter	Description	Address / Value
Morpho contract	Base deployment	`0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb`
`loanToken`	WETH	`0x4200000000000000000000000000000000000006`
`collateralToken`	USDC	`0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
`oracle`	On‑chain price feed	`0xD09048c8B568Dbf5f189302beA26c9edABFC4858`
`irm`	Adaptive‑Curve IRM	`0x46415998764C29aB2a25CbeA6254146D50D22687`
`lltv`	86 % liquidation-to-loan ratio (0.86 × 1e18)	`860000000000000000`

If you want to target a different market, simply swap out these addresses (all available in Morpho’s documentation and the morpho page.

You can get your target market from the Morpho app, in our demo we will target this market.

Each Morpho Market Curator can choose their desired collateral and loan token pairs based on market supply and demand. They can also choose their oracle of choice, this is very important because oracles are the least decentralized parts of a lending protocol so Curators can chose the most decentralized one that offers a specific market. In this case is chainlink. And also, depending on market liquidity and volatility they can choose a liquidation threshold, this means the amount of overcolateralization needed to get a loan, also curators can choose the way the liquidation threshold changes depending on market liquidity.

Solidity Implementation

Our contract will abstract the borrowing and repayment process into two single transactions.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";

// IERC20 interface needed to interact with USDC and WETH
interface IERC20 {
    function approve(address spender, uint256 amount) external returns (bool);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
}

// Morpho interface to get and repay loans
interface IMorpho{
    struct MarketParams {
        address loanToken;
        address collateralToken;
        address oracle;
        address irm;
        uint256 lltv;
    }

    function supplyCollateral(
        MarketParams calldata marketParams,
        uint256 amount,
        address onBehalf,
        bytes calldata data
    ) external;

    function borrow(
        MarketParams calldata marketParams,
        uint256 amount,
        uint256 maxShares,
        address onBehalf,
        address receiver
    ) external returns (uint256 assetsBorrowed, uint256 sharesBorrowed);

    function repay(
        MarketParams calldata marketParams,
        uint256 amount,
        uint256 maxShares,
        address onBehalf,
        bytes calldata data
    ) external returns (uint256 assetsRepaid, uint256 sharesRepaid);

    function withdrawCollateral(
        MarketParams calldata marketParams,
        uint256 amount,
        address onBehalf,
        address receiver
    ) external;
}

// Demo contrat that abstracts borrowing and repayment into two functions
contract MorphoBorrower is Ownable {
    address public constant morphoAddress = 0xBBBBBbbBBb9cC5e90e3b3Af64bdAF62C37EEFFCb;     // Morpho address on Base

    address public constant loanToken = 0x4200000000000000000000000000000000000006;         // WETH on base
    address public constant collateralToken = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913;   // USDC on base
    address public constant oracle = 0xD09048c8B568Dbf5f189302beA26c9edABFC4858;            // Chainlink oracle for our market
    address public constant irm = 0x46415998764C29aB2a25CbeA6254146D50D22687;               // Adaptative curve strategy for our market
    uint256 public constant lltv = 860000000000000000;                                      // 86% loan to liquidation treshold

    constructor() Ownable(msg.sender) {}

    // Our target morpho market settings
    IMorpho.MarketParams public marketParams = IMorpho.MarketParams({
        loanToken: loanToken,
        collateralToken: collateralToken,
        oracle: oracle,
        irm: irm,
        lltv: lltv
    });

    uint256 public sharesBorrowed; // Asset borrow tracking

    // Borrow WETH against USDC
    function borrowAgainstCollateral(uint256 collateralAmount, uint256 borrowAmount) external onlyOwner {
        // Transfer USDC from user and supply it as collateral in the Morpho market
        IERC20(collateralToken).transferFrom(msg.sender, address(this), collateralAmount);
        IERC20(collateralToken).approve(morphoAddress, collateralAmount);
        IMorpho(morphoAddress).supplyCollateral(
            marketParams,
            collateralAmount,
            address(this),
            ""
        );

        // Open a borrow position on this smart contract account and transfer the borrowed WETH to the user
        (uint256 assetsBorrowed, uint256 shares) = IMorpho(morphoAddress).borrow(
            marketParams,
            borrowAmount,
            0,
            address(this),
            address(this)
        );
        sharesBorrowed = shares;
        IERC20(loanToken).transfer(msg.sender, assetsBorrowed);
    }

    function repayAndWithdraw(uint256 repayAmount, uint256 collateralAmount) external onlyOwner {
        // Transfer WETH from the user and repay the debt with it
        IERC20(loanToken).transferFrom(msg.sender, address(this), repayAmount);
        IERC20(loanToken).approve(morphoAddress, repayAmount);
        IMorpho(morphoAddress).repay(
            marketParams,
            0,
            sharesBorrowed,
            address(this),
            ""
        );

        // Transfer back excess loanToken
        IERC20(loanToken).transfer(msg.sender, IERC20(loanToken).balanceOf(address(this)));

        // Withdraw all collateral and send to sender
        IMorpho(morphoAddress).withdrawCollateral(
            marketParams,
            collateralAmount,
            address(this),
            msg.sender
        );
    }
}

How to Use

On the BaseScan's USDC page, call approve(spender, amount) by setting your MorphoBorrower address as spender and e.g. 3000 (which equals 0.003 USDC, since USDC has 6 decimals).

Approve your contract from BaseScan's USDC page.

Then, borrow ETH by calling borrowAgainstCollateral(3000, 1_000_000_000) that is, 0.003 USDC collateral to borrow 0.000000001 WETH. At this point the WETH will be in your wallet and you are free to use it.

Try getting a 0.000000001 WETH with a 0.0003 collateral. Explore an on-chain example here.

To repay your debt, approve WETH on BaseScan using enough to cover principal + interest (e.g. 1_010_000_000). Then call repayAndWithdraw(1_010_000_000, 3000). Any excess WETH will automatically be refunded, and you’ll receive back your 0.003 USDC.

When the debt is repayed, notice how all excess WETH is sent back to us. Explore the on-chain transaction here.

Congratulations! You’ve now interacted with Morpho v1 to take out and repay a loan. From here you can retarget any other Morpho market by swapping out the addresses in MarketParams, or integrate these functions into your own dApp, DAO workflow or AI agent for fully programmable lending strategies.

How to make an Ethereum Real-Time dApp with no Spaghetti code

Ahmed Castro — Sat, 31 May 2025 18:55:13 +0000

I spent two weeks building a real time dApp and this article summarizes how I had to rethink architecture, design and UX for very fast blocktimes.

The dApp that my friend and I built is a simple War game: the player and the house each draw a card, and the highest card wins. The challenge is generating 100% on-chain random numbers with the lowest latency possible.

A betting game?

Yes! I personally have a thing for casinos. I understand that players have to be responsible when playing and that they can be dangerous, but still, I just happen to like them.

As a matter of fact, the first blockchain application I released was a casino.

That was on 2013, it was a Ruby on Rails backend connecting a local Dogecoin node I ran.

There were no smart contracts so I decided to take it down because I had no way to prove that I was operating in a fair manner.

I'm from a 3rd world country where building is hard, and back then it was harder. This was my first time monetizing my work so that project was very meaningful to me, also I was able to connect to many people trough IRC. Fun times!

Then, I learned about Ethereum smart contracts and decided to give it another try, this time using Chainlink VRF.

My second aptempt was Breadacle, a coin toss game where you bet if the bread will come out toasted or burnt.

Now my game had great provably guarantees of fairness, but was way too slow. Also a bit expensive and still had to trust the oracles.

Building a fast and fair game

Now, with blockchains with low latency I can build a fast, provably fair, oracleless game.

This time I did it with a Commit-Reveal scheme. A 3 transaction process that has to happen very fast.

Currently, our demo offers 1.3s average gameplay latency, this means 3 transactions in 1.3s which we think it's ok but not good enough. We believe we can bring it down to sub 500ms times with improvements in real time chains infra optimization and our own too.

In this architecture the player runs the client in their browser and the house (me) hosts a backend that responds to each players game.

Let's explore both starting with the backend

To be able to serve many players, the backend need to listen to new player games, index them in memory, and batch them with Multicall.

In case of down time, we can have a centralized database that serves as backup. Or better yet, using the on-chain state to recover. So what I'm saying is using the chain as backup, quite interesting IMO.

Alternatively, in case public RPCs for players are too slow, we can open an endpoint to query the game state from our server. This is debatable, on one had hand this can make the game more responsive but on the other it means that the house (me) could trick the player to reveal his random number before I post mine.

In this point in time we haven't been able to test in fullness beacuse we built the game in MegaETH (a 20ms block time chain, very fast!) but we haven't been able to access a web socket that right now is restricted to internal teams only.

We are ready to test it once we get access to that WSS key.

Let's now talk about the frontend, imo the most interesting part.

The frontend

Little by little I found out that building a real time ethereum dApp is very different from a normal dApp frontend or moblile app.

When building a real time dApp we have to stop thinking about listener/callback flows and start thinking similar to what a gamedev would.

As a quick side note, and a shameless self promotion, I used to be a gamedev. Built my own game engine, release a game on steam with it, built a C SDK used by 10s of thousands of players concurrently and was interviewed by Unreal Engine in a livestream.

So the most important thing that I noticed is that instead of developing with a listeners and callbacks in-mind we need a gameLoop() such as

gameLoop() {
  readState()
  processInputs()
  sendTransactions()
  processUI()
}

This function process the entire game and should be called continuously with fast intervals.

This is because real time apps, just like games, are very chaotic and if you try to do everything with callbacks, like a normal dApp, you will end with spaghetti code and glitchy UX.

This should apply not only to games, but also defi, social, id, etc...

So a few things to note while doing something like this:

1. Only read the state once per tick

A tick is one gameLopp() pass and you should only make one call() to ethereum. Each call takes from 100ms to 300ms, they are too slow.

And yes, this includes nonce and gasPrice checks. So don't use web3.js, ethers or viem abstractions, build your transactions manually yourself. Do it by keeping track of your nonces locally and reading the gasPrice only once every 5 minutes or so.

Also consider writing a function that returns all the information that you will need every tick. I like to call it "Singleton Call" and currently mine looks like this:

    function getGameState(address player) external view returns (
        uint player_balance,
        State gameState,
        bytes32 playerCommit,
        bytes32 houseHash,
        uint256 gameId,
        GameResult[] memory recentHistory
    ) {
       ...
    }

Notice how I'm returning a list of the 10 latest games so I can display them in the frontend. And I'm even returning the player balance by calling player.balance internally just so I don't have to do it a separate call.

Yes, this function doesn't look elegant so a good alternative is to use Multicall instead. I like it better with no Multicall in the frontend to keep it simple, but to each their own.

2. Buffer inputs

When the user clicks a button, don't react to it immediatly. Instead, store it in a list and process it later.

This concept is very familiar in fighting games, where you have to press a very precise combination on inputs to trigger special attacks.

Of course, my game is not as complex as a fighting game but still, we don't have control of the multithreading nature of javascript. So you have two options: a. implement an input buffer b. enter the realm of thread locks hell.

I recommend starting with a list-based buffer and handling only one action per tick. Later, you can try processing multiple actions per tick or updating the UI before handling input in the game loop. But in general I would stick with a simple buffer, if the app feels unresponsive, it might be a sign that the chain you're using is not fast enough.

3. Local storage wallet

Of course you don't want your user to click to confirm every transaction. So instead generate a private key on the player's browser like this:

function generateWallet() {
  const account = web3.eth.accounts.create();
  localStorage.setItem('localWallet', JSON.stringify({
    address: account.address,
    privateKey: account.privateKey
  }));
  return account;
}

This will generate a new wallet and store it in the browser's local storage.

Of course users should not treat it as their cold storage because it just isn't. If they clean their browser data goodbye wallet.

Regardless, this will give the users a good experience. Remember that my casino game is a 3-transaction process? In my case I can even reveal the random number automatically, even without the player clicking on something.

This is currently being used by Dark forest and other autonomous world gmames.

4. Paralelization

You have to think how make every action as soon as possible and how to give feedback as fast as possible to the player.

In my case this meant that I can start a new game even before the last one finished.

So normally a game will be played like this:

Player sends commitment tx
Player detects the house responded
Player sends reveal transaction

We can parallelize by starting a new game even before the reveal is confirmed on-chain. This is expecting that our new commit will be sequenced after the reveal does.

Also, by the time the player has the house randomness he can know the game result.

So in the UI, we can show the game result even before the result is calculated on-chain.

I like to call this "Optimistic Rendering".

I think optimizations like these are very important and should be implemented, but of course, we don't have control of the sequencer. We are doing this expecting that the sequencer would operate in a FiFo manner. So we will also need to implement a way to recover and auto-retry in the rare case the sequencer didn't acted as expected.

Thanks for reading!

Please try our demo in MegaETH testnet at realtimeplay.xyz and follow us and give us feedback at @RealTimePlayXYZ.

This is open source work as always so PRs very welcome on github.

Unruggable AI Agents with ZKML

Ahmed Castro — Wed, 22 Jan 2025 18:40:10 +0000

What was once speculation is now a reality: AI and blockchain are technologies with lots of synergy. Recently, AI agents have been actively participating in social media and on-chain, performing tasks like tipping users, swapping on-chain and more.

However, a critical problem remains: the current meta of AI agents lacks verifiability. This means the creator or owner of an AI agent can potentially tamper or impersonate the AI model, so users can't know what was done by the AI or by the creator. In this tutorial, we’ll explore how Zero Knowledge, shortened as ZK can provide the most secure and seamless experience for everyone in the AI agent space.

Why Zero Knowledge?

Zero Knowledge, provides two distinct capabilities: privacy and scalability.

For this tutorial, we’ll focus on the second one. Verifying the computation of a Machine Learning (ML) model directly is impossible to do on-chain by normal means because it's too expensive and in most cases won't even fit in a an Ethereum block. Instead, we’ll compute the ML model off-chain and use ZK to generate a proof of that computation. This proof can then be verified cheaply on-chain by a Solidity smart contract, ensuring trust without requiring full on-chain execution.

Building a Verifiable Tipper AI Agent

In this article we’ll create a Tipper AI agent that is able to decide who to send a tip to based on data provided that can be, for example, a list of comments on farcaster. We will need to create a smart contract that acts as a guardrail, ensuring the AI agent operates autonomously without being controlled by the creator. In order to achieve this, we’ll use EZKL, a tool for generating verifiable proofs of ML computations.

In this tutorial, you’ll learn how to:

Create a ZKML Verifier Contract
Generate a valid ZK Proof
Launch a simple Tip Token
Tip users when a valid ZK proof is submitted

EZKL: ZKML library for developers

EZKL provides convenient Google Colab notebooks to help you get started quickly. Here’s the Simple Demo Notebook.

Step 0: Generate an AI model

A model can, for example, decides who deserves a tip based who has the best comments on Farcaster, buy a token based on market conditions, or mint an NFT based on your singing skills. There are endless possibilities in terms of what an AI model can do on-chain.

In this example we'll keep it simple, we'll generate a model that just decides who deserves a 1000 token tip deterministically to an address provided.

Let's start by replacing the first block provided in google collab with the following. Also, replace tip_recipient_address with a wallet of your choice, this wallet will receive the tokens tipped by the AI.

# Check if notebook is in Colab
try:
    # Install ezkl and onnx if in Colab
    import google.colab
    import subprocess
    import sys
    subprocess.check_call([sys.executable, "-m", "pip", "install", "ezkl"])
    subprocess.check_call([sys.executable, "-m", "pip", "install", "onnx"])
except:
    pass  # Rely on local installation of ezkl otherwise

# Import required libraries
from torch import nn
import torch
import ezkl

# Define the address that will receive the tip
tip_recipient_address = 0x707e55a12557E89915D121932F83dEeEf09E5d70

# Convert the address to the format expected by EZKL
def address_to_byte_tensor(address):
    address_hex = f"{address:040x}"
    return torch.tensor([int(address_hex[i:i+2], 16) for i in range(0, len(address_hex), 2)], dtype=torch.uint8)

tip_recipient_tensor = address_to_byte_tensor(tip_recipient_address)
print(f"Tip Recipient Tensor: {tip_recipient_tensor}")

# Define a model that outputs the tipped address
class FixedHexAddressModel(nn.Module):
    def __init__(self, address_tensor):
        super(FixedHexAddressModel, self).__init__()
        self.output_value = address_tensor

    def forward(self, x):
        # Ignore input and always return the fixed address
        batch_size = x.size(0)
        return self.output_value.repeat(batch_size, 1)  # Repeat for batch size

# Instantiate the model
circuit = FixedHexAddressModel(tip_recipient_tensor)

# Example input
dummy_input = torch.ones(1, 1)  # Dummy input (not used by the model)

# Generate the output
output = circuit(dummy_input)
print(f"Output (Hex Address): {output}")

# Export the model to ONNX format
torch.onnx.export(
    circuit,
    dummy_input,
    "fixed_hex_address_model.onnx",
    input_names=["input"],
    output_names=["output"],
    dynamic_axes={"input": {0: "batch_size"}, "output": {0: "batch_size"}}
)

print("Model saved as 'fixed_hex_address_model.onnx'!")

Step 1: Create a Verifier Contract

Next, run all the other code snippets in Google Collab, this will generate a ZK circuit that is verifiable off-chain. Now we want to be able to verify on-chain, to do it run the following snippet. This will print a fully working Solidity verifier contract.

abi_path = 'test.abi'
sol_code_path = 'test.sol'

res = await ezkl.create_evm_verifier(
        vk_path,

        settings_path,
        sol_code_path,
        abi_path,
    )

assert res == True

with open(sol_code_path, 'r') as sol_file:
    sol_content = sol_file.read()
    print(sol_content)

The next step is deploying to your preferred chain. Please note that compiler optimizations must be enabled to successfully compile the contract. This is necessary because the generated contract is quite large and requires optimization to fit within deployment constraints.

Step 2: Generate a ZK Proof

Next, generate the ZK proof and encode it in the format that is expected by the verifier contract.

Run the following snippet and the proof will be printed.

abi_path = 'test.abi'
calldata = 'calldata2.proof'

res = ezkl.encode_evm_calldata(
        proof_path,
        calldata,
    )
# print(res)

calldata_hex = "0x" + ''.join(f"{byte:02x}" for byte in res)
print(calldata_hex)

EZKL generates a ZK proofs as raw calldata sent to the Verifier contract. This means that the proof must be sent using a low level evm CALL function instead of how you normally call another smart contract in solidity, more about this in Step 4.

Step 3. Launch the Tip Token

Deploy a simple ERC20 token that the AI agent will be able to interact with. Deploy the following contract that will mint some tokens to you.

// SPDX-License-Identifier: MIT
// Compatible with OpenZeppelin Contracts ^5.0.0
pragma solidity ^0.8.22;

import {ERC20} from "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract MyToken is ERC20 {
    constructor() ERC20("Tip Token", "TIPT") {
        _mint(msg.sender, 21_000_000 ether);
    }
}

Step 4: Build the Tipper Contract

The Tipper contract ensures that tokens are distributed only when a valid ZK proof is submitted. Deploy the following contract by replacing the HALO2_VERIFIER and TIP_TOKEN with the contract addresses you just deployed. Then, transfer at least 1000 Tip Tokens to this contract.

// SPDX-License-Identifier: GPL-3.0

pragma solidity >=0.7.0 <0.9.0;

interface Halo2Verifier {
    function verifyProof(bytes calldata proof, uint256[] calldata instances) external view;
}

interface IERC20 {
    function transfer(address to, uint256 value) external returns (bool);
}


contract AiAgentGuardrail {
    address HALO2_VERIFIER = 0x84fBBc680F4aB4240e8cF6C488aEca03bfF91d2E;
    address TIP_TOKEN = 0x84fBBc680F4aB4240e8cF6C488aEca03bfF91d2E;

    function verifyAndSendTip(bytes memory proofCalldata) public {
        (bool success, bytes memory data) = HALO2_VERIFIER.call(proofCalldata);
        if(success && data.length == 32 && uint8(data[31]) == 1)
            IERC20(TIP_TOKEN).transfer(extractTipRecipientFromProof(proofCalldata), 1_000 ether);
        else 
            revert("Could not verify proof");
    }

    function extractTipRecipientFromProof(bytes memory proofCalldata) internal pure returns (address) {
        bytes memory lastBytes = new bytes(20);
        for (uint i = 0; i < 20; i++) {
            lastBytes[20-1-i] = proofCalldata[proofCalldata.length - (1+i*32)];
        }
        return address(bytes20(abi.encodePacked(lastBytes)));
    }
}

Now call verifyAndSendTip by submitting the proof as parameter in the calldata format and once the transaction is confirmed 1000 tokens will be awarded to the tip recipient.

Next steps

By integrating ZK technology, we can create secure, autonomous AI agents that operate transparently on-chain. Next steps involve deepening into ZK learning and also training an AI model capable of performing interesting and exciting tasks. To get started with ZK I recommend TODO and to get started with training ML models, I recommend TODO.

A Brief History of zkVMs

Ahmed Castro — Fri, 10 Jan 2025 19:12:54 +0000

zkVMs have become a very important part of both Ethereum and its Layer 2s. However, there are many misconceptions and confusing bits of information around them.

This article aims to serve as a gentle introduction for users and researchers interested in understanding their importance, as well as for developers looking to get started with zkVMs so they can select the best option for them in case they want to build a project or contribute to an existing one.

From Low-Level Libraries to zkVMs

This section explores the evolution of ZK projects, from their origins in low-level libraries to the rise of zkDSLs and modern zkVM.

Early ZK implementations focused on low-level libraries, while newer general-purpose VMs improve developer experience but are harder to optimize for specific use cases.

The earliest implementations of ZK were direct translations of research papers into low-level libraries. A good example is libsnark, which was used to create Zcash. The need for generalization soon led to the creation of zkDSLs (domain-specific languages) like Circom, Noir, and ZoKrates. These are languages designed for building zk circuits. Meanwhile, libraries like Halo2 and Plonky2 emerged, focusing on providing zk capabilities within existing languages like Rust.

Main ZK projects falling into every catagory.

The second wave of end user applications were developed using zkDSLs, such as Tornado Cash for private transactions, and MACI for voting. Later, ZK made its way to L2s, making use of it's succinctness properties to reduce transaction costs. L2s often required synthetic virtual machines built on zk libraries and zkDSLs. For instance:

Polygon zkEVM was built by combining different libraries where it made more sense, zkSTARKs and Plonky2 for producing quick execution proofs and Circom for cheap verification. This resulted on the zkASM + PIL synthetic virtual machine.
Scroll was born by forking the Ethereum Foundation’s Privacy and Scaling Exploration (PSE)’s zkEVM, using the Halo2 zk library that aimed to be able to prove the Ethereum L1 directly.
Starkware introduced its own Cairo-VM that differs from the EVM but it's still able to be verified by Ethereum L1.

Notable projects and the libraries or DSLs they use

Then, a new need for generalization arose: building general-purpose zkVMs (like PIL, zkEVM, or Cairo VM) to allow developers to create applications using a common interface. These zkVMs could verify a variety of applications with a single circuit, extending beyond L2s to other use cases in the future. This allows developers to focus on building products, while the zkVMs ensure everything runs correctly and efficiently.

zkVMs today

Before zkVMs can be deployed to production, numerous audits and optimizations are necessary. That said, the pace of progress in this space has been remarkable. Notably, SP1 released OP Succinct, a fork of the OP Stack that transforms Optimism into a ZK Rollup. Meanwhile, Risc Zero introduced Zeth, which not only enables proofs for L2s but also represents a significant step toward long awaited light client implementations. This is a huge step towards Ethereum's decentralization and resilience. Additionally, Scroll announced plans to implement OpenVM on mainnet, making use of its modularity to create an OpenVM module of Ceno, Scroll’s new zkVM initiative.

How zkVMs Generate Value

You might wonder about the revenue model, given that zkVMs are open-source and free. The answer lies in the prover marketplace. As demand for proving grows, reliable and responsive provers will become essential. A decentralized prover marketplace, run by a security and governance token, could be the solution. Risc Zero currently has a closed beta of Bonsai, their prover network and SP1 announced their solution is a work in progress.

Will zkDSLs Die?

I don't think so. But this question is under debate at this point in time. A big part of the ZK community argue that zkDSLs like Circom or Noir will remain fundamental to Ethereum because they can cover a wider variety of cases and also because, with the right amount of time and resources, they can become more efficient that zkVMs. And by more efficient I mean cheaper to verify and faster to prove. However zkDSLs appear less suited for L2s, with zkVMs taking precedence. Privacy-focused applications will likely continue relying on zkDSLs.

Interestingly, zkVMs may enable new forms of privacy through client-side proving or light clients. For instance, zkVMs could facilitate applications where users run light nodes to verify states locally using zk proofs. This idea, while somewhat related, is worth exploring in a future article.

Is There Competition in the zkVM Space?

Absolutely. And yes, there’s drama too.
Multiple zkVM projects are competing for dominance, each with its own strengths and unique approaches. In my opinion, this is a good thing, as this competition and diversity only serve to enrich the Ethereum ecosystem. Below, you'll find an overview of the main projects, general information, my personal thoughts, and how to get started developing on each one:

Risc Zero

Announced: April 2022
Funding: $40M Series A led by Blockchain Capital and Bain Capital (July 2023)
Developer: Risc Zero
Social: @RiscZero on X

Risc Zero has been a pioneer in zkVMs and is currently the most advanced project in the field. This has earned it the trust of the community through its significant contributions to the zkVM space.

Get Started with Risc Zero

Run the following a script I wrote to set up and generate proofs:

git clone https://github.com/Turupawn/zkBenchmark.git
cd zkBenchmark
sh generate_proof_risc0.sh

Alternatively, explore the official documentation for detailed guidance.

SP1

Announced: Valentine’s Day 😇💘 2024
Funding: $55M Series A led by Paradigm (March 2024)
Developer: Succinct
Social: @SuccinctLabs on X

SP1 embodies the spirit of a classic Silicon Valley startup: highly competitive, aggressive, and focused on the market and metrics. This approach contrasts with Risc Zero's research-driven ethos.

Get Started with SP1

Run the following script I wrote to set up and generate proofs:

git clone https://github.com/Turupawn/zkBenchmark.git
cd zkBenchmark
sh generate_proof_sp1.sh

Explore their official documentation for more details.

OpenVM

Announced: December 2024
Funding: $20M Series A led by Paradigm and Standard Crypto (January 2024)
Developer: Axiom
Social: @OpenVM_org on X

OpenVM stands out for its modularity, providing a foundation for projects to build custom solutions while upstreaming their changes on GitHub to benefit all projects within the OpenVM ecosystem.

Get Started with OpenVM

Run the following script I wrote to set up and generate proofs:

git clone https://github.com/Turupawn/zkBenchmark.git
cd zkBenchmark
sh generate_proof_openvm.sh

Check the official documentation for more.

Conclusion

The zkVM space is incredibly fast paced and multidimensional. As new projects are constantly announced, it’s very important to explore the different approaches, and form your own opinion. This is a rapidly-changing ecosystem, and staying informed will help you navigate and leverage the opportunities within the Web3 world.

Thanks for reading this article!

Follow Filosofía Código on dev.to and in Youtube for everything related to Blockchain development.

L1SLOAD: Reading Arrays, Structs and Nested Mappings

Ahmed Castro — Thu, 31 Oct 2024 04:28:59 +0000

This article is a continuation of the L1SLOAD guide where we introduced its basic usage. Now, we will explore how to use l1sload to read more complex storage structures, such as mappings, structs, and both static and dynamic arrays.

The EVM handles the state by using 32-byte storage slots. In Solidity, this is abstracted to provide a better developer experience. However, to be read complex data structures with l1sload, it's essential to understand how Solidity manages storage at a lower level.

So let's start by understanding how static arrays are managed by the EVM.

Static Arrays

Static arrays are those with a fixed length declared at compile time. For example:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract L1ArrayDemo {
    uint[5] myArray;

    constructor() {
        myArray[0] = 10;
        myArray[1] = 20;
        myArray[2] = 30;
        myArray[3] = 40;
        myArray[4] = 50;
    }
}

On-chain, the first element of the array is stored in the variable’s storage slot, the second in slot + 1, the third in slot + 2, and so on.

L1ArrayDemo storage layout

To retrieve an element, you can simply add the array's slot to the array index of the value you're looking for. The formula looks like this:

\text{valueSlot } = \text{ arraySlot } + \text{ valueIndex}

Keep in mind, the length of a static array is not stored on-chain. It's only visible at compile time.

Another important note is that this approach works for types larger than 16 bytes (e.g., uint256, address, uint200). For smaller types like bool or uint8, Solidity applies data optimizations, which we’ll cover later in this guide.

The following contract demonstrates how to read an array from the L1ArrayDemo contract.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract L2ArrayDemo {
    address constant L1_BLOCKS_ADDRESS = 0x5300000000000000000000000000000000000001;
    address constant L1_SLOAD_ADDRESS = 0x0000000000000000000000000000000000000101;

    function getNum(address contractAddress, uint arraySlot, uint arrayIndex) public view returns(uint) {
        bool success;
        bytes memory returnValue;
        (success, returnValue) = L1_SLOAD_ADDRESS.staticcall(abi.encodePacked(contractAddress, arraySlot + arrayIndex));
        if(!success)
        {
            revert("L1SLOAD failed");
        }
        return abi.decode(returnValue, (uint));
    }
}

Dynamic Arrays

Unlike static arrays, dynamic arrays can grow after deployment. Because of this, Solidity stores them differently on-chain.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract L1DynamicArrayDemo {
    uint[] public myArray;

    constructor() {
        myArray.push(10);
        myArray.push(20);
        myArray.push(30);
    }
}

The storage slot for a dynamic array holds its length. The actual data is stored starting at KECCAK256(ARRAY_SLOT), with elements stored sequentially after that position, just like static arrays.

L1DynamicArrayDemo storage layout

To query a specific element, we use the following formula:

\text{valueSlot} = \text{KECCAK256(arraySLOT)} + \text{valueIndex}

Here’s an example contract that queries both the length and specific elements of a dynamic array:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract L2DynamicArrayDemo {
    address constant L1_BLOCKS_ADDRESS = 0x5300000000000000000000000000000000000001;
    address constant L1_SLOAD_ADDRESS = 0x0000000000000000000000000000000000000101;

    function retrieveArrayElement(address contractAddress, uint arraySlot, uint arrayIndex) public view returns(uint) {
        require(arrayIndex < getArrayLength(contractAddress, arraySlot), "Out of bounds index");
        uint arrayElementSlot = uint(
            keccak256(
                abi.encodePacked(arraySlot)
            )
        ) + arrayIndex;
        bool success;
        bytes memory returnValue;
        (success, returnValue) = L1_SLOAD_ADDRESS.staticcall(abi.encodePacked(contractAddress, arrayElementSlot));
        if(!success)
        {
            revert("L1SLOAD failed");
        }
        return abi.decode(returnValue, (uint));
    }

    function getArrayLength(address contractAddress, uint arraySlot) public view returns(uint) {
        bool success;
        bytes memory returnValue;
        (success, returnValue) = L1_SLOAD_ADDRESS.staticcall(abi.encodePacked(contractAddress, arraySlot));
        if(!success)
        {
            revert("L1SLOAD failed");
        }
        return abi.decode(returnValue, (uint));
    }
}

Special Case: Storing Values 16 Bytes or Smaller

Consider a dynamic array of uint104 values. Since two uint104 values can fit into a single 32-byte storage slot (with 48 bits, or 6 bytes, remaining unused), Solidity packs them together.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract L1Uint104Array {
    uint104[] public myArray;

    constructor() {
        myArray.push(10);
        myArray.push(20);
        myArray.push(30);
        myArray.push(40);
        myArray.push(50);
    }
}

L1Uint104Array storage layout

To query such values using l1sload, we first locate the appropriate slot, then use bitwise operations to extract the desired value. The following formula helps in calculating the slot:

\text{valueSlot} = \text{KECCAK256(arraySlot)} + \frac{\text{valueIndex}}{\text{slotSize} / \text{valueSize}}

However, retrieving the value also requires shifting the bits appropriately, which can be done using the right-shift operator.

\text{value} = \text{slotValue} \gg \left( \text{valueIndex} \% \frac{\text{slotSize}}{\text{valueSize}} * \text{valueSize} \right)

This method can also work for larger types like uint256 or address, but for simplicity and efficiency, I recommend sticking to the methods mentioned earlier for those types.

Here’s an example contract that queries data stored in a uint104 array:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract L2Uint104ArrayDemo {
    address constant L1_BLOCKS_ADDRESS = 0x5300000000000000000000000000000000000001;
    address constant L1_SLOAD_ADDRESS = 0x0000000000000000000000000000000000000101;

    function retrieveArrayElement(address contractAddress, uint arraySlot, uint arrayIndex) public view returns(uint104) {
        require(arrayIndex < getArrayLength(contractAddress, arraySlot), "Out of bounds index");

        uint arrayElementSlot = uint(
            keccak256(
                abi.encodePacked(arraySlot)
            )
        ) + arrayIndex / (uint(256)/104);
        bool success;
        bytes memory returnValue;
        (success, returnValue) = L1_SLOAD_ADDRESS.staticcall(abi.encodePacked(contractAddress, arrayElementSlot));
        if(!success)
        {
            revert("L1SLOAD failed");
        }
        uint104 returnValueUint = uint104(abi.decode(returnValue, (uint)) >> ((arrayIndex % (uint(256)/104)) * 104));
        return returnValueUint;
    }

    function getArrayLength(address contractAddress, uint arraySlot) public view returns(uint) {
        bool success;
        bytes memory returnValue;
        (success, returnValue) = L1_SLOAD_ADDRESS.staticcall(abi.encodePacked(contractAddress, arraySlot));
        if(!success)
        {
            revert("L1SLOAD failed");
        }
        return abi.decode(returnValue, (uint));
    }
}

Structs

Structs store their data contiguously, similar to arrays. If multiple elements can fit into a single 32-byte slot, Solidity will pack them together to optimize storage.

// SPDX-License-Identifier: GPL-3.0

pragma solidity ^0.8.20;

struct MyStruct {
    uint a;// 32 bytes (256 bits)
    address b; // 20 bytes (160 bits)
    bool c; // 1 byte (8 bits)
    uint d; // 32 bytes (256 bits) 
}

contract L1StructDemo {
    MyStruct myStruct;
    constructor() {
        myStruct = MyStruct(10,address(this),true,20);
    }
}

In the following example, the struct fields a, b, and c are packed across multiple slots. The variable d doesn’t fit into the second slot, so it is stored in the next available slot.

L1StructDemo storage layout

Reading structs requires accounting for the byte offsets of each field, using bitwise operations as necessary.

// SPDX-License-Identifier: GPL-3.0

pragma solidity ^0.8.20;

struct MyStruct {
    uint a;// 32 bytes (256 bits)
    address b; // 20 bytes (160 bits)
    bool c; // 1 byte (8 bits)
    uint d; // 32 bytes (256 bits) 
}

// This contract reads the balance of any holder on L1
contract L2StructDemo {
    address constant L1_BLOCKS_ADDRESS = 0x5300000000000000000000000000000000000001;
    address constant L1_SLOAD_ADDRESS = 0x0000000000000000000000000000000000000101;

    function getArrayLength(address contractAddress, uint structSlot) public view returns(MyStruct memory) {
        bool success;
        bytes memory returnValue;
        (success, returnValue) = L1_SLOAD_ADDRESS.staticcall(abi.encodePacked(contractAddress, structSlot, structSlot+1, structSlot+2));
        if(!success)
        {
            revert("L1SLOAD failed");
        }
        (uint256 slot0, uint256 slot1, uint slot2) = abi.decode(returnValue, (uint, uint, uint));
        address b = address(uint160(slot1));
        bool c = (slot1 >> 160) == 1;
        return MyStruct(slot0, b, c, slot2);
    }
}

Nesting Structures

Nested structures, such as mappings of arrays or structs containing arrays, follow the same rules as their underlying structures.

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract L1NestingDemo {
    mapping(uint => uint[] myArray) arrayMapping;
    constructor() {
        arrayMapping[0].push(10);
        arrayMapping[0].push(20);
        arrayMapping[0].push(30);
        arrayMapping[1].push(100);
        arrayMapping[1].push(200);
        arrayMapping[1].push(300);
    }
}

For example, reading from a mapping of arrays requires combining the formulas for mappings and dynamic arrays. The formula for mappings from the previous article, where introduced Mappings, works like this:

\text{KECCAK256(mappingKey, SLOT)}

The dynamic array formula we introduced in this article is the following:

\text{KECCAK256(SLOT)} + \text{arrayIndex}

We combine them and we get this one.

\text{valueSlot} = \text{KECCAK256(KECCAK256(mappingKey, mappingSlot) + arrayIndex)}

Data is stored in a pattern as illustrated below:

L1NestingDemo storage layout

Take a look at this example that demonstrates reading a mapping of arrays:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

contract L2NestingDemo {
    address constant L1_BLOCKS_ADDRESS = 0x5300000000000000000000000000000000000001;
    address constant L1_SLOAD_ADDRESS = 0x0000000000000000000000000000000000000101;

    function getArrayLength(address contractAddress, uint mappingSlot, uint mappingKey, uint arrayIndex) public view returns(uint) {
        uint mappingArraySlot = uint(
            keccak256(
                abi.encodePacked(
                    keccak256(abi.encodePacked(mappingKey,
                    mappingSlot)
                )
            )
        )) + arrayIndex;

        bool success;
        bytes memory returnValue;
        (success, returnValue) = L1_SLOAD_ADDRESS.staticcall(abi.encodePacked(contractAddress, mappingArraySlot));
        if(!success)
        {
            revert("L1SLOAD failed");
        }
        return abi.decode(returnValue, (uint));
    }
}

You can extend these principles to more complex data structures, such as an array of mappings, structs with arrays, or even mappings of mappings. The same logic applies in all cases.

Next steps

To improve your understanding of Solidity storage layout, check out the official documentation on the Layout of State section. Additionally, share your thoughts on the Ethereum Magicians Forum regarding the L1SLOAD RIP. With l1sload currently in development, your input is very important at this stage.

Thanks for reading!

Big Handmade Maps 100% On-Chain. Is it Possible?

Ahmed Castro — Wed, 04 Sep 2024 20:04:08 +0000

Dark Forest has shown that procedurally generated maps can be both engaging to the players and cost-effective in terms of on-chain gas usage. However, in their procgen article, Nalin and Gubsheep (AW developers) expressed that creating handmade maps on-chain presents significant challenges. Inspired by this, I decided to take on the challenge of finding a scalable way to store large handmade maps on-chain.

In this tutorial, we will go into both the theory and practice of creating fully on-chain handcrafted maps. By creating a game where the map has obstacles (mountains) stored in a Merkle Tree optimized for data compression. The player will have to submit Merkle Inclusion Proofs in order to advance.

Prefer to see the complete code? Head to Github to find all the code mentioned in this guide.

Starting with the Theory

Naive Implementation: Avoid this 🙅

Let's begin with a simple map where 0 represents grass and 1 represents mountains. The player can walk only on grass.

Our first intuition might be to declare a two-dimensional mapping and populate it like this:

mapping(uint x => mapping(uint y => terrainType)) map;
map[1][0] = 1;
map[2][2] = 1;
map[2][3] = 1;
map[0][3] = 1;

However, this approach is impractical for large maps due to the high gas costs and block size limitations. To store larger maps on-chain efficiently, we need a more scalable approach: Merkle Trees.

Merkleizing a Map

In this tutorial, we’ll transform a two-dimensional map into a Merkle tree. Players will prove their position by submitting a Merkle inclusion proof for the type of terrain they are on.

Why Merkleize a Map?

Merkleizing a map allows for proofs in logarithmic time, as opposed to linear. However, before Merkleizing, we must convert the map into a one-dimensional array using the following formula:

$LEAF_INDEX=y×MAP_WIDTH+x \text{LEAF{\textunderscore}INDEX} = y \times \text{MAP{\textunderscore}WIDTH} + x$

For example, our 4x4 map would convert into the following array:

Merkleizing a one-dimensional array is more straightforward than doing so for a two-dimensional map. The process involves hashing adjacent elements (positions 0 and 1, 2 and 3, etc.) until we reach the Merkle root.

When the game launches, the only data posted on-chain is the Merkle root. As players move, they submit Merkle proofs to verify their moves. This approach spreads the cost of storing the map across all players rather than placing the entire burden on the deployer.

In practice: Creating a big map on MUD

Supporting Material: How to Create and Autonomous World Game

Let's start by creating a new MUD project.

If you haven't installed MUD expand this and install the dependencies.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20
curl -L https://foundry.paradigm.xyz | bash export PATH=$PATH:~/.foundry/bin
sudo npm install -g pnpm

Once you're ready create a phaser template.

pnpm create mud@latest tutorial --template phaser
cd tutorial

The data

For this demo we will test a 32x32 map that we will define on the following public file.

packages/client/public/assets/map.json

{
    "map": [
        [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1],
        [0, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0],
        [0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
        [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
    ]
}

The table

Our table will consist of the players position, where every address can control only one player. Also a Singleton that holds the map merkle root as a commitment so no one can cheat later in the game.

packages/contracts/mud.config.ts

import { defineWorld } from "@latticexyz/world";

export default defineWorld({
  namespace: "app",
  enums: {
    Direction: [
      "Up",
      "Down",
      "Left",
      "Right"
    ]
  },
  tables: {
    PlayerPosition: {
      schema: {
        player: "address",
        x: "uint32",
        y: "uint32",
      },
      key: ["player"]
    },
    Map: {
      schema: {
        merkleRoot: "bytes32",
        size: "uint32"
      },
      key: [],
    },
  },
});

The contract

First let's remove the normal files.

rm packages/contracts/src/systems/IncrementSystem.sol packages/contracts/test/CounterTest.t.sol

Now let's commit to a merkle root in our PostDeploy script. Keep in mind that if you change the map data it will result in a new merkle root. I conveniently print the root on the terminal so you can grab it from there.

packages/contracts/script/PostDeploy.s.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

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 { Map } from "../src/codegen/index.sol";

contract PostDeploy is Script {
  function run(address worldAddress) external {
    // Specify a store so that you can use tables directly in PostDeploy
    StoreSwitch.setStoreAddress(worldAddress);

    // Load the private key from the `PRIVATE_KEY` environment variable (in .env)
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");

    // Start broadcasting transactions from the deployer account
    vm.startBroadcast(deployerPrivateKey);

    // Initialize Map
    Map.set(
      0xc99004d76733dbd8a4a6f3f3ecdc08392637d31e4339cce7c2b2aa7220e85fbf,
      32
    );

    vm.stopBroadcast();
  }
}

And define the movement logic on chain. Notice we verify the merkle inclusion proofs on chain to check if the player is walking into grass and not a mountain.

packages/contracts/src/systems/MyGameSystem.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

import { System } from "@latticexyz/world/src/System.sol";
import { PlayerPosition, PlayerPositionData, Map } from "../codegen/index.sol";
import { Direction } from "../codegen/common.sol";
import { getKeysWithValue } from "@latticexyz/world-modules/src/modules/keyswithvalue/getKeysWithValue.sol";
import { EncodedLengths, EncodedLengthsLib } from "@latticexyz/store/src/EncodedLengths.sol";

contract MyGameSystem is System {
    function spawn(uint32 x, uint32 y) public {
        address player = _msgSender();
        PlayerPosition.set(player, x, y);
    }

    function move(Direction direction, bytes32 positionLeaf, bytes32[] calldata proof) public {
        require(positionLeaf == bytes32(0), "Must move to walkable area"); // 0 is grass, 1 is mountains
        address player = _msgSender();
        PlayerPositionData memory playerPosition = PlayerPosition.get(player);

        uint32 x = playerPosition.x;
        uint32 y = playerPosition.y;

        if(direction == Direction.Up)
            y-=1;
        if(direction == Direction.Down)
            y+=1;
        if(direction == Direction.Left)
            x-=1;
        if(direction == Direction.Right)
            x+=1;

        PlayerPosition.set(player, x, y);

        require(verify(positionLeaf, Map.getMerkleRoot(), proof, getLeafIndex(x, y)), "invalid proof");
    }

    function verify(bytes32 leaf, bytes32 root, bytes32[] calldata proof, uint256 leafIndex) internal pure returns (bool) {
        bytes32 computedHash = leaf;
        for (uint256 i = 0; i < proof.length; i++) {
            if (leafIndex % 2 == 0) {
                computedHash = keccak256(abi.encodePacked(computedHash, proof[i]));
            } else {
                computedHash = keccak256(abi.encodePacked(proof[i], computedHash));
            }
            leafIndex /= 2;
        }
        return computedHash == root;
    }

    function getLeafIndex(uint32 x, uint32 y) public view returns (uint32) {
        // Calculate the leaf index as y * mapWidth + x
        return y * Map.getSize() + x;
    }
}

The client

The map interpreter

Let's modify the default Map System to interpret our map.json file.

packages/client/src/layers/phaser/systems/createMapSystem.ts

import { Tileset } from "../../../artTypes/world";
import { PhaserLayer } from "../createPhaserLayer";

export async function createMapSystem(layer: PhaserLayer) {
  const {
    scenes: {
      Main: {
        maps: {
          Main: { putTileAt },
        },
      },
    },
  } = layer;

  try {
    const response = await fetch('/assets/map.json');
    const data = await response.json();
    const map: number[][] = data.map;

    for (let y = 0; y < map.length; y++) {
      for (let x = 0; x < map[y].length; x++) {
        const coord = { x: x, y: y };
        const tileType = map[y][x];

        if (tileType === 1) {
          putTileAt(coord, Tileset.Mountain, "Foreground");
        } else {
          putTileAt(coord, Tileset.Grass, "Background");
        }
      }
    }
  } catch (error) {
    console.error("Error loading the map:", error);
  }
}

The Client: User interaction and Merkle Proofs generation

packages/client/src/layers/phaser/systems/myGameSystem.ts

import { Has, defineEnterSystem, defineSystem, getComponentValueStrict } from "@latticexyz/recs";
import { PhaserLayer } from "../createPhaserLayer";
import { 
  pixelCoordToTileCoord,
  tileCoordToPixelCoord
} from "@latticexyz/phaserx";
import { TILE_WIDTH, TILE_HEIGHT, Animations, Directions } from "../constants";
import { keccak256, toUtf8Bytes, zeroPadValue } from 'ethers';

// Utils
function hashFunction(data: Uint8Array): string {
  return keccak256(data);
}

function hexStringToBytes(hex: string): Uint8Array {
  if (hex.startsWith('0x')) {
    hex = hex.slice(2);
  }
  const bytes = new Uint8Array(hex.length / 2);
  for (let i = 0; i < hex.length; i += 2) {
    bytes[i / 2] = parseInt(hex.substr(i, 2), 16);
  }
  return bytes;
}

// Build the Merkle Tree
function buildMerkleTree(leafNodes: (number | string)[]): string {
  // Convert leaf nodes to bytes32 if they are numbers
  const processedLeafNodes = leafNodes.map(node =>
    typeof node === 'number' ? zeroPadValue("0x0"+node, 32) : node
  );

  let level = processedLeafNodes;
  while (level.length > 1) {
    const nextLevel: string[] = [];
    for (let i = 0; i < level.length; i += 2) {
      const left = level[i];
      const right = i + 1 < level.length ? level[i + 1] : left;
      const combined = new Uint8Array([
        ...hexStringToBytes(left),
        ...hexStringToBytes(right)
      ]);
      nextLevel.push(hashFunction(combined));
    }
    level = nextLevel;
  }
  return level[0];
}

// Hash the entire map
function hashMap(map: number[][]): string {
  const flatMap: (number | string)[] = map.flat();
  return buildMerkleTree(flatMap);
}

interface HashPath {
  leafHash: string;
  path: string[];  // Just hashes in the path
}

// Generate the hash path for a specific position
function generateHashPath(map: number[][], x: number, y: number): HashPath {
  const flatMap: (number | string)[] = map.flat();
  const index = y * map[0].length + x;
  const leafHash = typeof flatMap[index] === 'number'
    ? zeroPadValue("0x0"+flatMap[index], 32)
    : flatMap[index];
  const path: string[] = [];
  let level = flatMap.map(value => typeof value === 'number' ? zeroPadValue("0x0"+value, 32) : value);

  let currentIndex = index;

  while (level.length > 1) {
    const nextLevel: string[] = [];
    const levelLength = level.length;

    for (let i = 0; i < levelLength; i += 2) {
      const left = level[i];
      const right = i + 1 < levelLength ? level[i + 1] : left;
      const combined = new Uint8Array([
        ...hexStringToBytes(left),
        ...hexStringToBytes(right)
      ]);
      const parentHash = hashFunction(combined);
      nextLevel.push(parentHash);

      if (i === currentIndex || i + 1 === currentIndex) {
        const siblingIndex = i === currentIndex ? i + 1 : i;
        path.push(level[siblingIndex]); // Store only the hash
        currentIndex = Math.floor(currentIndex / 2); // Move up to the parent index
      }
    }
    level = nextLevel;
  }

  return { leafHash, path };
}

export const createMyGameSystem = (layer: PhaserLayer) => {
  const {
    world,
    networkLayer: {
      components: {
        PlayerPosition,
      },
      systemCalls: {
        spawn,
        move,
      }
    },
    scenes: {
        Main: {
            objectPool,
            input
        }
    }
  } = layer;

  let myPosition = {x: 0, y: 0};
  let map: number[][];

  const loadMap = async () => {
    try {
      const response = await fetch('/assets/map.json');
      const data = await response.json();
      map = data.map;
      console.log("Map loaded");

      const mapHash = hashMap(map);
      console.log('Map Hash (Merkle Root):', mapHash);

    } catch (error) {
      console.error("Error loading the map:", error);
    }
  };

  loadMap();

  input.pointerdown$.subscribe((event) => {
    const x = event.pointer.worldX;
    const y = event.pointer.worldY;
    const playerPosition = pixelCoordToTileCoord({ x, y }, TILE_WIDTH, TILE_HEIGHT);
    console.log(playerPosition)
    if(playerPosition.x == 0 && playerPosition.y == 0)
        return;
    spawn(playerPosition.x, playerPosition.y) 
  });

  input.onKeyPress((keys) => keys.has("W"), () => {
    myPosition.y -= 1;
    console.log(myPosition)

    const path = generateHashPath(map, myPosition.x, myPosition.y);

    console.log('Leaf Hash:', path.leafHash);
    console.log('Leaf Index:', myPosition.y * map[0].length + myPosition.x);

    const proof = path.path.map(hash => `0x${hash.slice(2)}`);
    console.log('Proof:', JSON.stringify(proof));

    move(Directions.UP, path.leafHash, proof);
  });

  input.onKeyPress((keys) => keys.has("S"), () => {
    myPosition.y += 1;
    console.log(myPosition)

    const path = generateHashPath(map, myPosition.x, myPosition.y);

    console.log('Leaf Hash:', path.leafHash);
    console.log('Leaf Index:', myPosition.y * map[0].length + myPosition.x);

    const proof = path.path.map(hash => `0x${hash.slice(2)}`);
    console.log('Proof:', JSON.stringify(proof));

    move(Directions.DOWN, path.leafHash, proof);
  });

  input.onKeyPress((keys) => keys.has("A"), () => {
    myPosition.x -= 1;
    console.log(myPosition)

    const path = generateHashPath(map, myPosition.x, myPosition.y);

    console.log('Leaf Hash:', path.leafHash);
    console.log('Leaf Index:', myPosition.y * map[0].length + myPosition.x);

    const proof = path.path.map(hash => `0x${hash.slice(2)}`);
    console.log('Proof:', JSON.stringify(proof));

    move(Directions.LEFT, path.leafHash, proof);
  });

  input.onKeyPress((keys) => keys.has("D"), () => {
    myPosition.x += 1;
    console.log(myPosition)

    const path = generateHashPath(map, myPosition.x, myPosition.y);

    console.log('Leaf Hash:', path.leafHash);
    console.log('Leaf Index:', myPosition.y * map[0].length + myPosition.x);

    const proof = path.path.map(hash => `0x${hash.slice(2)}`);
    console.log('Proof:', JSON.stringify(proof));

    move(Directions.RIGHT, path.leafHash, proof);
  });

  defineEnterSystem(world, [Has(PlayerPosition)], ({entity}) => {
    const playerObj = objectPool.get(entity, "Sprite");
    playerObj.setComponent({
        id: 'animation',
        once: (sprite) => {
            sprite.play(Animations.Player);
        }
    })
  });

  defineSystem(world, [Has(PlayerPosition)], ({ entity }) => {
    const playerPosition = getComponentValueStrict(PlayerPosition, entity);
    myPosition = playerPosition;
    const pixelPosition = tileCoordToPixelCoord(playerPosition, TILE_WIDTH, TILE_HEIGHT);

    const playerObj = objectPool.get(entity, "Sprite");

    playerObj.setComponent({
      id: "position",
      once: (sprite) => {
        sprite.setPosition(pixelPosition.x, pixelPosition.y);
      }
    })
  })
};

The Animations, System Calls and Registration

packages/client/src/mud/createSystemCalls.ts

import { getComponentValue } from "@latticexyz/recs";
import { ClientComponents } from "./createClientComponents";
import { SetupNetworkResult } from "./setupNetwork";
import { singletonEntity } from "@latticexyz/store-sync/recs";

export type SystemCalls = ReturnType<typeof createSystemCalls>;

export function createSystemCalls(
  { worldContract, waitForTransaction }: SetupNetworkResult,
  { PlayerPosition }: ClientComponents,
) {
  const spawn = async (x: number, y: number) => {
    const tx = await worldContract.write.app__spawn([x, y]);
    await waitForTransaction(tx);
    return getComponentValue(PlayerPosition, singletonEntity);
  };

  const move = async (direction: number, leaf: string, proof: string[]) => {
    const tx = await worldContract.write.app__move([direction, leaf, proof]);
    await waitForTransaction(tx);
    return getComponentValue(PlayerPosition, singletonEntity);
  };

  return {
    spawn, move
  };
}

packages/client/src/layers/phaser/configurePhaser.ts

import Phaser from "phaser";
import {
  defineSceneConfig,
  AssetType,
  defineScaleConfig,
  defineMapConfig,
  defineCameraConfig,
} from "@latticexyz/phaserx";
import worldTileset from "../../../public/assets/tilesets/world.png";
import { TileAnimations, Tileset } from "../../artTypes/world";
import { Sprites, Assets, Maps, Scenes, TILE_HEIGHT, TILE_WIDTH, Animations } from "./constants";

const ANIMATION_INTERVAL = 200;

const mainMap = defineMapConfig({
  chunkSize: TILE_WIDTH * 64, // tile size * tile amount
  tileWidth: TILE_WIDTH,
  tileHeight: TILE_HEIGHT,
  backgroundTile: [Tileset.Grass],
  animationInterval: ANIMATION_INTERVAL,
  tileAnimations: TileAnimations,
  layers: {
    layers: {
      Background: { tilesets: ["Default"] },
      Foreground: { tilesets: ["Default"] },
    },
    defaultLayer: "Background",
  },
});

export const phaserConfig = {
  sceneConfig: {
    [Scenes.Main]: defineSceneConfig({
      assets: {
        [Assets.Tileset]: {
          type: AssetType.Image,
          key: Assets.Tileset,
          path: worldTileset,
        },
        [Assets.MainAtlas]: {
          type: AssetType.MultiAtlas,
          key: Assets.MainAtlas,
          // Add a timestamp to the end of the path to prevent caching
          path: `/assets/atlases/atlas.json?timestamp=${Date.now()}`,
          options: {
            imagePath: "/assets/atlases/",
          },
        },
      },
      maps: {
        [Maps.Main]: mainMap,
      },
      sprites: {
        [Sprites.Player]: {
          assetKey: Assets.MainAtlas,
          frame: "sprites/golem/idle/0.png",
        },
      },
      animations: [
        {
          key: Animations.Player,
          assetKey: Assets.MainAtlas,
          startFrame: 0,
          endFrame: 3,
          frameRate: 6,
          repeat: -1,
          prefix: "sprites/golem/idle/",
          suffix: ".png",
        },
      ],
      tilesets: {
        Default: {
          assetKey: Assets.Tileset,
          tileWidth: TILE_WIDTH,
          tileHeight: TILE_HEIGHT,
        },
      },
    }),
  },
  scale: defineScaleConfig({
    parent: "phaser-game",
    zoom: 1,
    mode: Phaser.Scale.NONE,
  }),
  cameraConfig: defineCameraConfig({
    pinchSpeed: 1,
    wheelSpeed: 1,
    maxZoom: 3,
    minZoom: 1,
  }),
  cullingChunkSize: TILE_HEIGHT * 16,
};

packages/client/src/layers/phaser/constants.ts

export enum Scenes {
  Main = "Main",
}

export enum Maps {
  Main = "Main",
}

export enum Animations {
  Player = "Player",
}
export enum Sprites {
  Player,
}

export enum Directions {
  UP = 0,  
  DOWN = 1,  
  LEFT = 2,  
  RIGHT = 3,  
}

export enum Assets {
  MainAtlas = "MainAtlas",
  Tileset = "Tileset",
}

export const TILE_HEIGHT = 32;
export const TILE_WIDTH = 32;

packages/client/src/layers/phaser/systems/registerSystems.ts

import { PhaserLayer } from "../createPhaserLayer";
import { createCamera } from "./createCamera";
import { createMapSystem } from "./createMapSystem";
import { createMyGameSystem } from "./myGameSystem";

export const registerSystems = (layer: PhaserLayer) => {
  createCamera(layer);
  createMapSystem(layer);
  createMyGameSystem(layer);
};

For simplicity, on this demo we set a fixed camera where the 0,0 position is the top left position.

packages/client/src/layers/phaser/createPhaserLayer.ts

import { createPhaserEngine } from "@latticexyz/phaserx";
import { namespaceWorld } from "@latticexyz/recs";
import { NetworkLayer } from "../network/createNetworkLayer";
import { registerSystems } from "./systems";

export type PhaserLayer = Awaited<ReturnType<typeof createPhaserLayer>>;
type PhaserEngineConfig = Parameters<typeof createPhaserEngine>[0];

export const createPhaserLayer = async (networkLayer: NetworkLayer, phaserConfig: PhaserEngineConfig) => {
  const world = namespaceWorld(networkLayer.world, "phaser");

  const { game, scenes, dispose: disposePhaser } = await createPhaserEngine(phaserConfig);
  world.registerDisposer(disposePhaser);

  const { camera } = scenes.Main;

  camera.phaserCamera.setBounds(0, 0, 500, 500);
  camera.phaserCamera.centerOn(0, 0);

  const components = {};

  const layer = {
    networkLayer,
    world,
    game,
    scenes,
    components,
  };

  registerSystems(layer);

  return layer;
};

Run the game

Install the ethers dependency.

cd packages/client/
pnpm install ethers
cd ../..

Run the game.

pnpm dev

Closing thoughts

Encoding expressive worlds

Instead of a 0 1 data. We could encode data into each position with no gas usage increase. For example we could encode the following structure:

struct MapTile {
  uint8 terrainType;
  uint8 fishApparationRate;
  uint8 wildCatApparationRate;
  bool isExplored;
  string npcDialog;
  [...]
}

Only submit proofs once

To save gas and offchain indexing, players should submit a merkle proof once. All results should be stored so players in the future can query the map that has been already explored on chain.

For simplicity I'm not doing it on this guide but it should look something like this:

mapping(uint x => mapping(uint y => bytes32 terrainData)) mapData;
mapping(uint x => mapping(uint y => bool isExplored)) mapIsExplored;

function move(Direction direction, bytes32 positionLeaf, bytes32[] calldata proof) public {
  [...]
  mapData[x][y] = positionLeaf;
  mapIsExplored[x][y] = true;
}

function move(Direction direction) public {
  [...]
  require(mapIsExplored[x][y], "Tile not explored yet");
}

Bigger maps require Web2 optimizations

Maybe a specialized indexer backend that precalculates the whole map merkle inclusion proofs so players can consult. In terms of gas cost this demo scales quite well do it's logarithmic verification costs. For example I did the following test:

Moving in a 32x32 map costs 92,687 gas.
Moving a 1000x1000 map cost 103,440 gas.

As you can see, the map size doesn't impact too much on the gas cost. The rest of the logic on the move function is more significant.

For this test I used this map whose merkle root computes to 0x86f3820289c9335418aaa077ba6a1dc6ab512203cc1faecb450bfbfe64021e98.

Thanks for reading this guide!

Follow Filosofía Código on dev.to and in Youtube for everything related to Blockchain development.

How to create an Information Asymmetric Autonomous World: MUD + Circom

Ahmed Castro — Tue, 20 Aug 2024 04:47:37 +0000

In this tutorial, we will create a 100% on-chain game with information asymmetry, in other words, an autonomous world where the private state and computation but remain fully verifiable on Ethereum. We will use MUD, the engine for Autonomous Worlds, and Circom, the most widely used language for ZK circuits.

You will learn to:

Combine the Circom language with the MUD framework
Create an autonomous world with private computation and variables
Generate zk-SNARK proofs directly from your browser using Snark.js

The game
Create a MUD project
1. The state
2. The circuits
2.a. Attack SNARK
2.b. Defense SNARK
2.c. Verifier contracts
3. The contracts
4. UI and Phaser
5. zk-WASM in the Client
6. Las animaciones
7. Bind everything together
8. Run the game

The game

At the start of the game, each player spawns 4 units that they can move across the map. Each unit is of a different type, but this information is private, visible only to the owner of the units.

🐉 que le gana al 🧙 que le gana al 🧌 que le gana al 🗡️. Pero el 🗡️ es una unidad especial pues es la única que puede derrotar al 🐉

The four defined types in the game are the 🐉, which beats the 🧙, which beats the 🧌, which beats the 🗡️. However, the 🗡️ is a special unit because it's the only one that can defeat the 🐉. Battles are done using a zk-SNARK that reveals the attacker's type, followed by another zk-SNARK that computes the battle's outcome without revealing the type of the unit that was attacked.

The game's architecture places all public data and logic in MUD, while all privacy-related aspects are handled in Circom

Create a MUD project

pnpm create mud@latest tutorial
cd tutorial

1. Define the State

The characters' positions are kept public, defined in the MUD tables. Additionally, we add some ZK commitments to ensure that no one can cheat, this part will make more sense in the upcoming ZK section.

packages/contracts/mud.config.ts

import { defineWorld } from "@latticexyz/world";

export default defineWorld({
  namespace: "app",
  enums: {
    Direction: [
      "Up",
      "Down",
      "Left",
      "Right"
    ]
  },
  tables: {
    Character: {
      schema: {
        x: "int32",
        y: "int32",
        owner: "address",
        id: "uint32",
        attackedAt: "uint32",
        attackedByValue: "uint32",
        revealedValue: "uint32",
        isDead: "bool",
      },
      key: ["x", "y"]
    },
    PlayerPrivateState: {
      schema: {
        account: "address",
        commitment: "uint256",
      },
      key: ["account"]
    },
    VerifierContracts: {
      schema: {
        revealContractAddress: "address",
        defendContractAddress: "address"
      },
      key: [],
    },
  },
});

2. Create the combat circuits

The battle circuits consist of the attack SNARK and the defense SNARK.

a. Attack SNARK

When a character attacks, it reveals its type. To ensure the player isn't cheating, we create a SNARK that hashes the initial types defined by the player at the start of the game. The circuit ensures that the player has assigned a character of each type, and then everything is hashed together with a privateSalt, which acts as a private key and prevents brute-force attacks to uncover the initial state the player committed to. This hash is called a commitment, which is stored in a MUD table that will help verify that everything happened correctly. More details on this will be covered in the contracts section below.

packages/zk/circuits/reveal/reveal.circom

pragma circom 2.0.0;

include "../circomlib/circuits/poseidon.circom";
include "../circomlib/circuits/comparators.circom";

template spawn() {
    // Input signals
    signal input character1;
    signal input character2;
    signal input character3;
    signal input character4;
    signal input privateSalt;
    signal input characterReveal; // The character index to reveal (1, 2, 3, or 4)
    signal input valueReveal; // The value that is claimed to be assigned to the character

    // Output signal for the hash
    signal output hash;

    // Poseidon hash calculation
    component poseidonComponent = Poseidon(5);
    poseidonComponent.inputs[0] <== character1;
    poseidonComponent.inputs[1] <== character2;
    poseidonComponent.inputs[2] <== character3;
    poseidonComponent.inputs[3] <== character4;
    poseidonComponent.inputs[4] <== privateSalt;
    hash <== poseidonComponent.out;

    // Comparator components for character reveal verification
    component isChar1 = IsEqual();
    component isChar2 = IsEqual();
    component isChar3 = IsEqual();
    component isChar4 = IsEqual();
    isChar1.in[0] <== characterReveal;
    isChar1.in[1] <== 1;
    isChar2.in[0] <== characterReveal;
    isChar2.in[1] <== 2;
    isChar3.in[0] <== characterReveal;
    isChar3.in[1] <== 3;
    isChar4.in[0] <== characterReveal;
    isChar4.in[1] <== 4;

    // Value check depending on the revealed character
    component checkChar1 = IsEqual();
    component checkChar2 = IsEqual();
    component checkChar3 = IsEqual();
    component checkChar4 = IsEqual();

    checkChar1.in[0] <== isChar1.out * character1 + (1 - isChar1.out) * 0;
    checkChar1.in[1] <== valueReveal;

    checkChar2.in[0] <== isChar2.out * character2 + (1 - isChar2.out) * 0;
    checkChar2.in[1] <== valueReveal;

    checkChar3.in[0] <== isChar3.out * character3 + (1 - isChar3.out) * 0;
    checkChar3.in[1] <== valueReveal;

    checkChar4.in[0] <== isChar4.out * character4 + (1 - isChar4.out) * 0;
    checkChar4.in[1] <== valueReveal;

    signal validReveal1;
    signal validReveal2;
    signal validReveal3;
    signal validReveal4;

    validReveal1 <== checkChar1.out;
    validReveal2 <== checkChar2.out;
    validReveal3 <== checkChar3.out;
    validReveal4 <== checkChar4.out;

    signal validReveal <== validReveal1 + validReveal2 + validReveal3 + validReveal4;
    validReveal === 1;

    // Comparators to check for presence of values 1, 2, 3, 4
    component isOne1 = IsEqual();
    component isOne2 = IsEqual();
    component isOne3 = IsEqual();
    component isOne4 = IsEqual();
    isOne1.in[0] <== character1;
    isOne1.in[1] <== 1;
    isOne2.in[0] <== character2;
    isOne2.in[1] <== 1;
    isOne3.in[0] <== character3;
    isOne3.in[1] <== 1;
    isOne4.in[0] <== character4;
    isOne4.in[1] <== 1;
    signal oneExists <== isOne1.out + isOne2.out + isOne3.out + isOne4.out;
    oneExists === 1;

    component isTwo1 = IsEqual();
    component isTwo2 = IsEqual();
    component isTwo3 = IsEqual();
    component isTwo4 = IsEqual();
    isTwo1.in[0] <== character1;
    isTwo1.in[1] <== 2;
    isTwo2.in[0] <== character2;
    isTwo2.in[1] <== 2;
    isTwo3.in[0] <== character3;
    isTwo3.in[1] <== 2;
    isTwo4.in[0] <== character4;
    isTwo4.in[1] <== 2;
    signal twoExists <== isTwo1.out + isTwo2.out + isTwo3.out + isTwo4.out;
    twoExists === 1;

    component isThree1 = IsEqual();
    component isThree2 = IsEqual();
    component isThree3 = IsEqual();
    component isThree4 = IsEqual();
    isThree1.in[0] <== character1;
    isThree1.in[1] <== 3;
    isThree2.in[0] <== character2;
    isThree2.in[1] <== 3;
    isThree3.in[0] <== character3;
    isThree3.in[1] <== 3;
    isThree4.in[0] <== character4;
    isThree4.in[1] <== 3;
    signal threeExists <== isThree1.out + isThree2.out + isThree3.out + isThree4.out;
    threeExists === 1;

    component isFour1 = IsEqual();
    component isFour2 = IsEqual();
    component isFour3 = IsEqual();
    component isFour4 = IsEqual();
    isFour1.in[0] <== character1;
    isFour1.in[1] <== 4;
    isFour2.in[0] <== character2;
    isFour2.in[1] <== 4;
    isFour3.in[0] <== character3;
    isFour3.in[1] <== 4;
    isFour4.in[0] <== character4;
    isFour4.in[1] <== 4;
    signal fourExists <== isFour1.out + isFour2.out + isFour3.out + isFour4.out;
    fourExists === 1;
}

component main {public [characterReveal, valueReveal]} = spawn();

b. Defense SNARK

When a character is attacked, it enters a state where it cannot move or attack. To exit this state, the character must present a SNARK that proves its defense was successful without revealing its type. This is achieved through a circuit that verifies the defense based on the public type of the attacker and the private type of the defender.

packages/zk/circuits/defend/defend.circom

pragma circom 2.0.0;

include "../circomlib/circuits/poseidon.circom";
include "../circomlib/circuits/comparators.circom";

template CharacterBattleCheck() {
    // Input signals
    signal input character1;
    signal input character2;
    signal input character3;
    signal input character4;
    signal input privateSalt;
    signal input characterTarget; // 1-based index: 1 for character1, 2 for character2, etc.
    signal input attackerLevel;

    // Output signal for the hash
    signal output hash;

    // Output signal for the battle result
    signal output battleResult;

    // Poseidon hash calculation
    component poseidonComponent = Poseidon(5);
    poseidonComponent.inputs[0] <== character1;
    poseidonComponent.inputs[1] <== character2;
    poseidonComponent.inputs[2] <== character3;
    poseidonComponent.inputs[3] <== character4;
    poseidonComponent.inputs[4] <== privateSalt;
    hash <== poseidonComponent.out;

    // Create binary indicators for each target
    signal isTarget1;
    signal isTarget2;
    signal isTarget3;
    signal isTarget4;

    // Check if characterTarget matches 1, 2, 3, or 4
    component isTarget1Eq = IsEqual();
    isTarget1Eq.in[0] <== characterTarget;
    isTarget1Eq.in[1] <== 1;
    isTarget1 <== isTarget1Eq.out;

    component isTarget2Eq = IsEqual();
    isTarget2Eq.in[0] <== characterTarget;
    isTarget2Eq.in[1] <== 2;
    isTarget2 <== isTarget2Eq.out;

    component isTarget3Eq = IsEqual();
    isTarget3Eq.in[0] <== characterTarget;
    isTarget3Eq.in[1] <== 3;
    isTarget3 <== isTarget3Eq.out;

    component isTarget4Eq = IsEqual();
    isTarget4Eq.in[0] <== characterTarget;
    isTarget4Eq.in[1] <== 4;
    isTarget4 <== isTarget4Eq.out;

    // Ensure exactly one of the targets is selected
    signal sumTargets;
    sumTargets <== isTarget1 + isTarget2 + isTarget3 + isTarget4;
    sumTargets === 1;

    // Use separate variables to hold the selected character values
    signal selectedCharacter1;
    signal selectedCharacter2;
    signal selectedCharacter3;
    signal selectedCharacter4;

    // Enforce that only one of the selectedCharacter variables holds the value
    selectedCharacter1 <== isTarget1 * character1;
    selectedCharacter2 <== isTarget2 * character2;
    selectedCharacter3 <== isTarget3 * character3;
    selectedCharacter4 <== isTarget4 * character4;

    // Aggregate the selected character value
    signal selectedCharacter;
    selectedCharacter <== selectedCharacter1 + selectedCharacter2 + selectedCharacter3 + selectedCharacter4;

    // Compare attackerLevel and selectedCharacter
    component compareLevel = LessThan(4); // Assuming levels are within 4 bits (0-15)
    compareLevel.in[0] <== selectedCharacter;
    compareLevel.in[1] <== attackerLevel;
    signal attackerWinsNormal <== compareLevel.out;

    // Special rule: attackerLevel == 1 and selectedCharacter == 4
    component isAttackerLevelOneEq = IsEqual();
    isAttackerLevelOneEq.in[0] <== attackerLevel;
    isAttackerLevelOneEq.in[1] <== 1;
    signal isAttackerLevelOne <== isAttackerLevelOneEq.out;

    component isCharacterTargetFourEq = IsEqual();
    isCharacterTargetFourEq.in[0] <== selectedCharacter;
    isCharacterTargetFourEq.in[1] <== 4;
    signal isCharacterTargetFour <== isCharacterTargetFourEq.out;

    signal attackerWinsSpecial;
    attackerWinsSpecial <== isAttackerLevelOne * isCharacterTargetFour;

    // Determine if the attacker wins either normally or via special rule
    signal attackerWins;
    attackerWins <== attackerWinsNormal + attackerWinsSpecial;

    // Convert attackerWins to a binary value (0 or 1)
    signal isAttackerWins;
    signal zeroFlag;
    signal oneFlag;

    // Determine zeroFlag: 1 if attackerWins == 0, else 0
    zeroFlag <== attackerWins * (attackerWins - 1);
    oneFlag <== 1 - zeroFlag;

    // isAttackerWins should be 1 if attackerWins > 0, else 0
    isAttackerWins <== attackerWins - zeroFlag;

    // Calculate the battleResult: 1 if defender wins, 2 if attacker wins
    signal defenderWins;
    defenderWins <== 1 - isAttackerWins;

    // Output battleResult: 1 if defender wins, 2 if attacker wins
    battleResult <== 1 + isAttackerWins;

    log(battleResult);
}

component main {public [characterTarget, attackerLevel]} = CharacterBattleCheck();

As you can see, we're using the Poseidon and comparator libraries, install them.

cd packages/zk/circuits
git clone https://github.com/iden3/circomlib.git

c. Create the verifier contracts

Get into the reveal circuit folder.

cd reveal

Compile the circuit.

circom reveal.circom --r1cs --wasm --sym

Generate the groth16 ceremony and verifier contract.

snarkjs powersoftau new bn128 12 pot12_0000.ptau -v
snarkjs powersoftau contribute pot12_0000.ptau pot12_0001.ptau --name="First contribution" -v
snarkjs powersoftau prepare phase2 pot12_0001.ptau pot12_final.ptau -v
snarkjs groth16 setup reveal.r1cs pot12_final.ptau reveal_0000.zkey
snarkjs zkey contribute reveal_0000.zkey reveal_0001.zkey --name="1st Contributor Name" -v
snarkjs zkey export verificationkey reveal_0001.zkey verification_key.json
snarkjs zkey export solidityverifier reveal_0001.zkey ../../../contracts/src/RevealVerifier.sol

Put it in the MUD contract folder.

mkdir ../../../client/public/zk_artifacts/
cp reveal_js/reveal.wasm ../../../client/public/zk_artifacts/
cp reveal_0001.zkey ../../../client/public/zk_artifacts/reveal_final.zkey

Now do the same with the defense circuit.

cd ../defend

Compile.

circom defend.circom --r1cs --wasm --sym

And generate the verifier.

snarkjs powersoftau new bn128 12 pot12_0000.ptau -v
snarkjs powersoftau contribute pot12_0000.ptau pot12_0001.ptau --name="First contribution" -v
snarkjs powersoftau prepare phase2 pot12_0001.ptau pot12_final.ptau -v
snarkjs groth16 setup defend.r1cs pot12_final.ptau defend_0000.zkey
snarkjs zkey contribute defend_0000.zkey defend_0001.zkey --name="1st Contributor Name" -v
snarkjs zkey export verificationkey defend_0001.zkey verification_key.json
snarkjs zkey export solidityverifier defend_0001.zkey ../../../contracts/src/DefendVerifier.sol

Put it in the contracts folder.

mkdir ../../../client/public/zk_artifacts/
cp defend_js/defend.wasm ../../../client/public/zk_artifacts/
cp defend_0001.zkey ../../../client/public/zk_artifacts/defend_final.zkey

You should also change the generic name Groth16Verifier to RevealVerifier and DefendVerifier, respectively, in the contracts we just placed in packages/client/public/zk_artifacts/.

3. Game Logic

Delete a couple of files that we won't be using.

cd ../../../../
rm packages/contracts/src/systems/IncrementSystem.sol packages/contracts/test/CounterTest.t.sol

All the game logic is defined in Solidity. It includes the initial spawn, followed by the attack and defense phases, each with their respective ZK proofs. We also added a killUnresponsiveCharacter function, which eliminates a player if they fail to present their defense ZK proof within a given time.

packages/contracts/src/systems/MyGameSystem.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

import { System } from "@latticexyz/world/src/System.sol";
import { Character, CharacterData, VerifierContracts } from "../codegen/index.sol";
import { PlayerPrivateState } from "../codegen/index.sol";
import { Direction } from "../codegen/common.sol";
import { getKeysWithValue } from "@latticexyz/world-modules/src/modules/keyswithvalue/getKeysWithValue.sol";

import { EncodedLengths, EncodedLengthsLib } from "@latticexyz/store/src/EncodedLengths.sol";

interface ICircomRevealVerifier {
    function verifyProof(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[3] calldata _pubSignals) external view returns (bool);
}

interface ICircomDefendVerifier {
    function verifyProof(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[4] calldata _pubSignals) external view returns (bool);
}

contract MyGameSystem is System {
  function spawn(int32 x, int32 y, uint256 commitment) public {
    //require(PlayerPrivateState.getCommitment(_msgSender()) == 0, "Player already spawned");

    Character.set(x, y, _msgSender(), 1, 0, 0, 0, false);
    Character.set(x, y + 1, _msgSender(), 2, 0, 0, 0, false);
    Character.set(x, y + 2, _msgSender(), 3, 0, 0, 0, false);
    Character.set(x, y + 3, _msgSender(), 4, 0, 0, 0, false);

    PlayerPrivateState.set(_msgSender(), commitment);
  }

  function move(int32 characterAtX, int32 characterAtY, Direction direction) public {
    CharacterData memory character = Character.get(characterAtX, characterAtY);

    //require(!character.isDead, "Character is dead");
    require(character.attackedAt == 0, "Character is under attack");
    require(character.owner == _msgSender(), "Only owner");

    int32 x = characterAtX;
    int32 y = characterAtY;

    if(direction == Direction.Up)
      y -= 1;
    if(direction == Direction.Down)
      y += 1;
    if(direction == Direction.Left)
      x -= 1;
    if(direction == Direction.Right)
      x += 1;

    CharacterData memory characterAtDestination = Character.get(x, y);
    require(characterAtDestination.owner == address(0), "Destination is occupied");

    Character.deleteRecord(characterAtX, characterAtY);
    Character.set(x, y, _msgSender(), character.id, 0, 0, character.revealedValue, false);
  }

  function attack(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[3] calldata _pubSignals,
    int32 fromX, int32 fromY, int32 toX, int32 toY
  ) public {
    ICircomRevealVerifier(VerifierContracts.getRevealContractAddress()).verifyProof(_pA, _pB, _pC, _pubSignals);
    uint256 commitment = _pubSignals[0];
    uint256 characterReveal = _pubSignals[1];
    uint256 valueReveal = _pubSignals[2];

    require(PlayerPrivateState.getCommitment(_msgSender()) == commitment, "Invalid commitment");
    require(characterReveal == Character.getId(fromX, fromY), "Invalid attacker id");
    require(Character.getOwner(fromX, fromY) == _msgSender(), "You're not the planet owner");
    Character.setRevealedValue(fromX, fromY, uint32(valueReveal));
    Character.setAttackedAt(toX, toY, uint32(block.timestamp));
    Character.setAttackedByValue(toX, toY, uint32(valueReveal));
  }

  function defend(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[4] calldata _pubSignals,
    int32 x, int32 y
  ) public {
    ICircomDefendVerifier(VerifierContracts.getDefendContractAddress()).verifyProof(_pA, _pB, _pC, _pubSignals);

    uint256 commitment = _pubSignals[0];
    uint256 battleResult = _pubSignals[1];
    uint256 characterTarget = _pubSignals[2];
    uint256 attackerLevel = _pubSignals[3];

    require(PlayerPrivateState.getCommitment(Character.getOwner(x, y)) == commitment, "Invalid commitment");
    require(characterTarget == Character.getId(x, y), "Invalid character id");
    require(attackerLevel == Character.getAttackedByValue(x, y), "Invalid attacked by value in proof");

    if(battleResult == 1) { // defense won
      Character.setAttackedAt(x, y, 0);
      Character.setAttackedByValue(x, y, 0);
    } else { // attack won
      Character.setIsDead(x, y, true);
    }
  }

  function killUnresponsiveCharacter(int32 x, int32 y) public {
    uint32 attackedAt = Character.getAttackedAt(x, y);
    uint32 MAX_WAIT_TIME = 1 minutes;
    require(attackedAt>0 && (attackedAt - uint32(block.timestamp)) >  MAX_WAIT_TIME, "Can kill character now");
    Character.setIsDead(x, y, true);
  }
}

Remember that in MUD, we don't use traditional constructors. This is because a single System contract can manage the state of multiple worlds. Instead, we use the PostDeploy contract, where we deploy the verifier contracts.

packages/contracts/script/PostDeploy.s.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

import { Script } from "forge-std/Script.sol";
import { console } from "forge-std/console.sol";
import { StoreSwitch } from "@latticexyz/store/src/StoreSwitch.sol";

import { RevealVerifier } from "../src/RevealVerifier.sol";
import { DefendVerifier } from "../src/DefendVerifier.sol";

import { IWorld } from "../src/codegen/world/IWorld.sol";

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

contract PostDeploy is Script {
  function run(address worldAddress) external {
    // Specify a store so that you can use tables directly in PostDeploy
    StoreSwitch.setStoreAddress(worldAddress);

    // Load the private key from the `PRIVATE_KEY` environment variable (in .env)
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");

    // Start broadcasting transactions from the deployer account
    vm.startBroadcast(deployerPrivateKey);

    address revealVerifier = address(new RevealVerifier());
    VerifierContracts.setRevealContractAddress(revealVerifier);

    address defendVerifier = address(new DefendVerifier());
    VerifierContracts.setDefendContractAddress(defendVerifier);

    vm.stopBroadcast();
  }
}

4. The Client with Phaser + Snarkjs

Create the file that will handle the user interface logic. This file manages mouse actions for dragging to move, connecting two characters to attack, and clicking to defend. Additionally, it defines the logic for animations.

packages/client/src/layers/phaser/systems/myGameSystem.ts

import { Has, defineEnterSystem, defineExitSystem, defineSystem, getComponentValueStrict, getComponentValue } from "@latticexyz/recs";
import { PhaserLayer } from "../createPhaserLayer";
import { 
  pixelCoordToTileCoord,
  tileCoordToPixelCoord
} from "@latticexyz/phaserx";
import { TILE_WIDTH, TILE_HEIGHT, Animations, Directions } from "../constants";

function decodePosition(hexString) {
    if (hexString.startsWith('0x')) {
        hexString = hexString.slice(2);
    }

    const halfLength = hexString.length / 2;
    const firstHalfHex = hexString.slice(0, halfLength);
    const secondHalfHex = hexString.slice(halfLength);

    const firstHalfInt32 = getSignedInt32(firstHalfHex);
    const secondHalfInt32 = getSignedInt32(secondHalfHex);

    return { x: firstHalfInt32, y: secondHalfInt32 };
}

function getSignedInt32(hexStr) {
    const int32Value = parseInt(hexStr.slice(-8), 16);

    if (int32Value > 0x7FFFFFFF) {
        return int32Value - 0x100000000;
    }
    return int32Value;
}

function encodePosition(x: number, y: number): string {
    const xHex = int256ToHex(x);
    const yHex = int256ToHex(y);

    // Concatenate the two 32-byte hex values to form a 64-byte hex string
    return '0x' + xHex + yHex;
}

function int256ToHex(value: number): string {
    // If the value is negative, convert it to a 256-bit unsigned integer
    if (value < 0) {
        value = BigInt('0x10000000000000000000000000000000000000000000000000000000000000000') + BigInt(value);
    } else {
        value = BigInt(value);
    }

    // Convert the integer to a hexadecimal string, ensuring it has 64 characters (256 bits)
    let hexStr = value.toString(16);
    while (hexStr.length < 64) {
        hexStr = '0' + hexStr;
    }

    return hexStr;
}

export const createMyGameSystem = (layer: PhaserLayer) => {
  const {
    world,
    networkLayer: {
      components: { Character },
      systemCalls: { spawn, move, attack, defend, playerEntity }
    },
    scenes: {
        Main: { objectPool, input }
    }
  } = layer;

  let startPoint: { x: number; y: number } | null = null;
  let draggedEntity: string | null = null;

  let playerRectangle1 = objectPool.get("PlayerRectangle1", "Rectangle");
  let playerRectangle2 = objectPool.get("PlayerRectangle2", "Rectangle");
  let playerRectangle3 = objectPool.get("PlayerRectangle3", "Rectangle");
  let playerRectangle4 = objectPool.get("PlayerRectangle4", "Rectangle");
  let arrowLine1 = objectPool.get("ArrowLine1", "Line");
  let arrowLine2 = objectPool.get("ArrowLine2", "Line");
  let arrowLine3 = objectPool.get("ArrowLine3", "Line");

  let secretCharacterValues = [0, 4, 1, 2, 3];
  let privateSalt = 123;

  input.pointerdown$.subscribe((event) => {
    const { worldX, worldY } = event.pointer;
    const player = pixelCoordToTileCoord({ x: worldX, y: worldY }, TILE_WIDTH, TILE_HEIGHT);

    if (player.x === 0 && player.y === 0) return;

    let coordinates = pixelCoordToTileCoord({ x: worldX, y: worldY }, TILE_WIDTH, TILE_HEIGHT);
    let encodedPosition = encodePosition(coordinates.x, coordinates.y);

    const character = getComponentValue(Character, encodedPosition);

    if (character) {
        startPoint = { x: worldX, y: worldY };
        draggedEntity = `${player.x}-${player.y}`;
    } else {
        spawn(player.x, player.y, 123);
    }
  });

  input.pointermove$.subscribe((event) => {
    if (startPoint && draggedEntity) {
        const { worldX, worldY } = event.pointer;

        // Draw the main line
        arrowLine1.setComponent({
          id: "line",
          once: (line) => {
            line.visible = true;
            line.isStroked = true;
            line.setFillStyle(0xff00ff);
            line.geom.x1 = startPoint.x;
            line.geom.y1 = startPoint.y;
            line.geom.x2 = worldX;
            line.geom.y2 = worldY;
          },
        });

        // Draw an arrowhead effect at the end point
        const arrowLength = 20;
        const angle = Math.atan2(worldY - startPoint.y, worldX - startPoint.x);

        arrowLine2.setComponent({
          id: "line",
          once: (line) => {
            line.visible = true;
            line.isStroked = true;
            line.setFillStyle(0x00ff00);
            line.geom.x1 = worldX;
            line.geom.y1 = worldY;
            line.geom.x2 = worldX - arrowLength * Math.cos(angle - Math.PI / 6);
            line.geom.y2 = worldY - arrowLength * Math.sin(angle - Math.PI / 6);
          },
        });

        arrowLine3.setComponent({
          id: "line",
          once: (line) => {
            line.visible = true;
            line.isStroked = true;
            line.setFillStyle(0x00ff00);
            line.geom.x1 = worldX;
            line.geom.y1 = worldY;
            line.geom.x2 = worldX - arrowLength * Math.cos(angle + Math.PI / 6);
            line.geom.y2 = worldY - arrowLength * Math.sin(angle + Math.PI / 6);
          },
        });
    }
  });

  input.pointerup$.subscribe((event) => {
    if (startPoint && draggedEntity) {

      const { worldX, worldY } = event.pointer;

      const startTile = pixelCoordToTileCoord(startPoint, TILE_WIDTH, TILE_HEIGHT);
      const endTile = pixelCoordToTileCoord({ x: worldX, y: worldY }, TILE_WIDTH, TILE_HEIGHT);

      const encodedDestinationPosition = encodePosition(endTile.x, endTile.y);
      const destinationCharacter = getComponentValue(Character, encodedDestinationPosition);
      const direction = calculateDirection(startTile, endTile);

      if(startTile.x == endTile.x
          && startTile.y == endTile.y)
      {

        console.log(`Defending character at (${startTile.x}, ${startTile.y})`);

        defend(startTile.x, startTile.y,
        {
          character1: secretCharacterValues[1],
          character2: secretCharacterValues[2],
          character3: secretCharacterValues[3],
          character4: secretCharacterValues[4],
          privateSalt: privateSalt,
          characterTarget: destinationCharacter.id,
          attackerLevel: destinationCharacter.attackedByValue
        });

      } else if (destinationCharacter) {
        const encodedStartPosition = encodePosition(startTile.x, startTile.y);
        const startCharacter = getComponentValue(Character, encodedStartPosition);

        attack(startTile.x, startTile.y, endTile.x, endTile.y,
          {
            character1: secretCharacterValues[1],
            character2: secretCharacterValues[2],
            character3: secretCharacterValues[3],
            character4: secretCharacterValues[4],
            privateSalt: privateSalt,
            characterReveal: startCharacter.id,
            valueReveal: secretCharacterValues[startCharacter.id]
          }
        );
        console.log(`Attacked character from (${startTile.x}, ${startTile.y}) to (${endTile.x}, ${endTile.y})`);
      } else if (direction != null) {
        move(startTile.x, startTile.y, direction);
        console.log(`Moved character from (${startTile.x}, ${startTile.y}) to (${endTile.x}, ${endTile.y}) in direction ${direction}`);
      } 

      startPoint = null;
      draggedEntity = null;
    }
  });

  defineEnterSystem(world, [Has(Character)], ({ entity }) => {
    const character = getComponentValue(Character, entity);

    const characterObj = objectPool.get(entity, "Sprite");
    characterObj.setComponent({
      id: 'animation',
      once: (sprite) => {
        let characterAnimation = character.revealedValue;
        const playerIsOwner = "0x" + playerEntity.slice(26).toLowerCase() == "" + character.owner.toLowerCase()
        if(playerIsOwner) {
          characterAnimation = secretCharacterValues[character.id];
        }
        if(playerIsOwner) {
          const characterPosition = tileCoordToPixelCoord(decodePosition(entity), TILE_WIDTH, TILE_HEIGHT);
          let rectangle = null

          switch (character.id)  {
            case 1:
              rectangle = playerRectangle1;
              break;
            case 2:
              rectangle = playerRectangle2;
              break;
            case 3:
              rectangle = playerRectangle3;
              break;
            case 4:
              rectangle = playerRectangle4;
              break;
          }

          rectangle.setComponent({
            id: "rectangle",
            once: (rectangle) => {
              rectangle.setPosition(characterPosition.x, characterPosition.y);
              rectangle.setSize(32,32);
              rectangle.setFillStyle(0x0000ff);
              rectangle.setAlpha(0.25);
            },
          });

        }
        switch (characterAnimation)  {
          case 1:
            sprite.play(Animations.A);
            break;
          case 2:
            sprite.play(Animations.B);
            break;
          case 3:
            sprite.play(Animations.C);
            break;
          case 4:
            sprite.play(Animations.D);
            break;
          default:
            sprite.play(Animations.Unknown);
        }
      }
    });
  });

  defineExitSystem(world, [Has(Character)], ({ entity }) => {
    objectPool.remove(entity);
  });

  defineSystem(world, [Has(Character)], ({ entity }) => {
    const character = getComponentValue(Character, entity);
    if(!character)
      return;
    const pixelPosition = tileCoordToPixelCoord(decodePosition(entity), TILE_WIDTH, TILE_HEIGHT);
    const characterObj = objectPool.get(entity, "Sprite");

    if (character.isDead) {
      characterObj.setComponent({
        id: 'animation',
        once: (sprite) => {
          sprite.play(Animations.Dead);
        }
      });
    } else if (character.attackedAt != 0) {
      characterObj.setComponent({
        id: 'animation',
        once: (sprite) => {
          sprite.play(Animations.Attacked);
        }
      });
    } else
    {
      characterObj.setComponent({
        id: 'animation',
        once: (sprite) => {
          let characterAnimation = character.revealedValue;
          const playerIsOwner = "0x" + playerEntity.slice(26).toLowerCase() == "" + character.owner.toLowerCase()
          if(playerIsOwner) {
            characterAnimation = secretCharacterValues[character.id];
          }
          if(playerIsOwner) {
            //sprite.setBackgroundColor("#0000ff");
          }
          switch (characterAnimation)  {
            case 1:
              sprite.play(Animations.A);
              break;
            case 2:
              sprite.play(Animations.B);
              break;
            case 3:
              sprite.play(Animations.C);
              break;
            case 4:
              sprite.play(Animations.D);
              break;
            default:
              sprite.play(Animations.Unknown);
          }
        }
      });
    }

    characterObj.setComponent({
      id: "position",
      once: (sprite) => {
        sprite.setPosition(pixelPosition.x, pixelPosition.y);
      }
    });

    arrowLine1.setComponent({
      id: "line",
      once: (line) => {
        line.visible = false;
      },
    });

    arrowLine2.setComponent({
      id: "line",
      once: (line) => {
        line.visible = false;
      },
    });

    arrowLine3.setComponent({
      id: "line",
      once: (line) => {
        line.visible = false;
      },
    });
  });

  function calculateDirection(start: { x: number, y: number }, end: { x: number, y: number }) {
    if (end.y < start.y) return Directions.UP;
    if (end.y > start.y) return Directions.DOWN;
    if (end.x < start.x) return Directions.LEFT;
    if (end.x > start.x) return Directions.RIGHT;
    return null;
  }
};

5. Client-Ethereum and Client-SNARK interaction

First, we need to install the library that will help us produce SNARKs.

cd packages/client/
pnpm install snarkjs

Now we can define the on-chain transactions and the generation of ZK proofs.

packages/client/src/mud/createSystemCalls.ts

import { getComponentValue } from "@latticexyz/recs";
import { ClientComponents } from "./createClientComponents";
import { SetupNetworkResult } from "./setupNetwork";
import { singletonEntity } from "@latticexyz/store-sync/recs";
import { groth16 } from "snarkjs";

export type SystemCalls = ReturnType<typeof createSystemCalls>;

export function createSystemCalls(
  { worldContract, waitForTransaction, playerEntity }: SetupNetworkResult,
  { Character }: ClientComponents,
) {
  const spawn = async (x: number, y: number) => {
    const { proof, publicSignals } = await groth16.fullProve(
      {
          character1: 4,
          character2: 1,
          character3: 2,
          character4: 3,
          privateSalt: 123,
          characterReveal: 1,
          valueReveal: 4,
      },
      "./zk_artifacts/reveal.wasm",
      "./zk_artifacts/reveal_final.zkey"
    );
    let commitment : number = publicSignals[0];
    const tx = await worldContract.write.app__spawn([x, y, commitment]);
    await waitForTransaction(tx);
    return getComponentValue(Character, singletonEntity);
  };

  const move = async (x: number, y: number, direction: number) => {
    const tx = await worldContract.write.app__move([x, y, direction]);
    await waitForTransaction(tx);
    return getComponentValue(Character,  singletonEntity);
  }

  const attack = async (fromX: number, fromY: number, toX: number, toY: number, circuitInputs: any) => {
    const { proof, publicSignals } = await groth16.fullProve(circuitInputs,
      "./zk_artifacts/reveal.wasm",
      "./zk_artifacts/reveal_final.zkey"
    );

    let pa = proof.pi_a
    let pb = proof.pi_b
    let pc = proof.pi_c
    pa.pop()
    pb.pop()
    pc.pop()

    const tx = await worldContract.write.app__attack([pa, pb, pc, publicSignals, fromX, fromY, toX, toY]);
    await waitForTransaction(tx);
    return getComponentValue(Character,  singletonEntity);
  }

  const defend = async (x: number, y: number, circuitInputs: any) => {
    const { proof, publicSignals } = await groth16.fullProve(circuitInputs,
      "./zk_artifacts/defend.wasm",
      "./zk_artifacts/defend_final.zkey"
    );

    let pa = proof.pi_a
    let pb = proof.pi_b
    let pc = proof.pi_c
    pa.pop()
    pb.pop()
    pc.pop()

    const tx = await worldContract.write.app__defend([pa, pb, pc, publicSignals, x, y]);
    await waitForTransaction(tx);
    return getComponentValue(Character,  singletonEntity);
  }

  return {
    spawn, move, attack, defend, playerEntity
  };
}

6. Adding Game Animations

You can use any animations you like, but if you want to use the same ones I'm using, you can download these assets:

packages/art/sprites/A/1.png

packages/art/sprites/B/1.png

packages/art/sprites/C/1.png

packages/art/sprites/D/1.png

packages/art/sprites/Attacked/1.png

packages/art/sprites/Dead/1.png

packages/art/sprites/Unknown/1.png

Generate the atlas.

cd packages/art
yarn
yarn generate-multiatlas-sprites

Y definimos las animaciones en el juego. Aquí puedes agregar animaciones de varios cuadros y establecer el comportamiento y velocidad de estas.

Define the game animations. You can set the fames, speed and behaviour.

packages/client/src/layers/phaser/configurePhaser.ts

import Phaser from "phaser";
import {
  defineSceneConfig,
  AssetType,
  defineScaleConfig,
  defineMapConfig,
  defineCameraConfig,
} from "@latticexyz/phaserx";
import worldTileset from "../../../public/assets/tilesets/world.png";
import { TileAnimations, Tileset } from "../../artTypes/world";
import { Assets, Maps, Scenes, TILE_HEIGHT, TILE_WIDTH, Animations } from "./constants";

const ANIMATION_INTERVAL = 200;

const mainMap = defineMapConfig({
  chunkSize: TILE_WIDTH * 64, // tile size * tile amount
  tileWidth: TILE_WIDTH,
  tileHeight: TILE_HEIGHT,
  backgroundTile: [Tileset.Grass],
  animationInterval: ANIMATION_INTERVAL,
  tileAnimations: TileAnimations,
  layers: {
    layers: {
      Background: { tilesets: ["Default"] },
      Foreground: { tilesets: ["Default"] },
    },
    defaultLayer: "Background",
  },
});

export const phaserConfig = {
  sceneConfig: {
    [Scenes.Main]: defineSceneConfig({
      assets: {
        [Assets.Tileset]: {
          type: AssetType.Image,
          key: Assets.Tileset,
          path: worldTileset,
        },
        [Assets.MainAtlas]: {
          type: AssetType.MultiAtlas,
          key: Assets.MainAtlas,
          // Add a timestamp to the end of the path to prevent caching
          path: `/assets/atlases/atlas.json?timestamp=${Date.now()}`,
          options: {
            imagePath: "/assets/atlases/",
          },
        },
      },
      maps: {
        [Maps.Main]: mainMap,
      },
      sprites: {
      },
      animations: [
        {
          key: Animations.A,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 3,
          repeat: -1,
          duration: 1,
          prefix: "sprites/A/",
          suffix: ".png",
        },
        {
          key: Animations.B,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 3,
          repeat: -1,
          duration: 1,
          prefix: "sprites/B/",
          suffix: ".png",
        },
        {
          key: Animations.C,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 3,
          repeat: -1,
          duration: 1,
          prefix: "sprites/C/",
          suffix: ".png",
        },
        {
          key: Animations.D,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 3,
          repeat: -1,
          duration: 1,
          prefix: "sprites/D/",
          suffix: ".png",
        },
        {
          key: Animations.Dead,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 12,
          repeat: -1,
          duration: 1,
          prefix: "sprites/Dead/",
          suffix: ".png",
        },
        {
          key: Animations.Unknown,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 12,
          repeat: -1,
          duration: 1,
          prefix: "sprites/Unknown/",
          suffix: ".png",
        },
        {
          key: Animations.Attacked,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 12,
          repeat: -1,
          duration: 1,
          prefix: "sprites/Attacked/",
          suffix: ".png",
        },
      ],
      tilesets: {
        Default: {
          assetKey: Assets.Tileset,
          tileWidth: TILE_WIDTH,
          tileHeight: TILE_HEIGHT,
        },
      },
    }),
  },
  scale: defineScaleConfig({
    parent: "phaser-game",
    zoom: 1,
    mode: Phaser.Scale.NONE,
  }),
  cameraConfig: defineCameraConfig({
    pinchSpeed: 1,
    wheelSpeed: 1,
    maxZoom: 3,
    minZoom: 1,
  }),
  cullingChunkSize: TILE_HEIGHT * 16,
};

7. Bind everything together

packages/client/src/layers/phaser/constants.ts

export enum Scenes {
  Main = "Main",
}

export enum Maps {
  Main = "Main",
}

export enum Animations {
  A = "A",
  B = "B",
  C = "C",
  D = "D",
  Dead = "Dead",
  Unknown = "Unknown",
  Attacked = "Attacked",
}

export enum Directions {
  UP = 0,  
  DOWN = 1,  
  LEFT = 2,  
  RIGHT = 3,  
}

export enum Assets {
  MainAtlas = "MainAtlas",
  Tileset = "Tileset",
}

export const TILE_HEIGHT = 32;
export const TILE_WIDTH = 32;

packages/client/src/layers/phaser/systems/registerSystems.ts

import { PhaserLayer } from "../createPhaserLayer";
import { createCamera } from "./createCamera";
import { createMapSystem } from "./createMapSystem";
import { createMyGameSystem } from "./myGameSystem";

export const registerSystems = (layer: PhaserLayer) => {
  createCamera(layer);
  createMapSystem(layer);
  createMyGameSystem(layer);
};

8. Run the game

Go back to the project's root directory.

cd ../../

And run the game.

pnpm dev

Now you can open the game in two different browsers. Each player can spawn by clicking on an empty space. Drag to an adjacent empty space to move. Drag to another player to attack. Click on an attacked player to generate a defense SNARK.

In the game, click to spawn, drag to an adjacent empty space to move, drag to an opponent to attack, and click to defend.

Thanks for reading this guide!

Follow Filosofía Código on dev.to and in Youtube for everything related to Blockchain development.

ZK 🤝 Autonomous Worlds: Guide on Creating Privacy On-Chain Games

Ahmed Castro — Mon, 29 Jul 2024 15:15:55 +0000

Zero Knowledge solves the problem of any type of game requiring privacy to be fully played on-chain. For example playing poker on-chain by enabling players to keep their hands private.

In this tutorial, we'll implement Minesweeper on-chain. A Game Master will hide bombs on a map, and if a player steps on one, the Game Master can prove it, causing the player to "explode".

We will learn how to create a game where bombs are hidden on a private ZK state, if a player steps into one it will "explode"

This tutorial is part of a three-part series on ZK and autonomous worlds. If you haven't yet, be sure to check out my previous posts.

Create a new MUD project
1. The state
2. The circuit
3. The contracts
4. The client
5. Bind everything together
6. The prover
Going forward

Create a new MUD project

We'll be using Node 20 (>=18 should be ok), pnpm and foundry. Here are the commands if you haven't installed them yet.

Instalación de dependencias



curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20
curl -L https://foundry.paradigm.xyz | bash export PATH=$PATH:~/.foundry/bin
sudo npm install -g pnpm

Once installed create a new MUD project.



pnpm create mud@latest tutorial
cd tutorial

During the installation process select phaser.

1. Define the public sate

Everyone will be able to see each other's positions on-chain and publicly. However bomb positions will be stored on-chain, a commitment and a verifier contract will be stored on chain to prove the validity of the private computation.

packages/contracts/mud.config.ts



import { defineWorld } from "@latticexyz/world";

export default defineWorld({
  namespace: "app",
  enums: {
    Direction: [
      "Up",
      "Down",
      "Left",
      "Right"
    ]
  },
  tables: {
    Player: {
      schema: {
        player: "address",
        x: "int32",
        y: "int32",
        isDead: "bool",
      },
      key: ["player"]
    },
    ZKState: {
      schema: {
        bombsCommitment: "uint32",
        circomVerifier: "address"
      },
      key: [],
    },
  }
});

2. Compute privately on the Circuit

The circuit will handle all the private computation, for this tutorial we'll use Circom.

Let's create the ZK folder structure, following a very similar file structure of a typical Mud project.



mkdir packages/zk
mkdir packages/zk/circuits
mkdir packages/zk/prover
mkdir packages/zk/prover/zk_artifacts

The detonateBomb circuit is capable of producing proofs that a player stepped into one of three bombs secretly placed on the map without revealing the the rest of the bombs. This is done by returning 1 as the result signal if a player steped into one, otherwise 0 is returned. Notice the commitment signal, this is the hash of all the bombs position. This will be later stored on chain to make sure the Game Master can't modify the bomb positions later on the game.

packages/zk/circuits/detonateBomb.circom



pragma circom 2.0.0;

include "circomlib/circuits/poseidon.circom";
include "circomlib/circuits/comparators.circom";

template commitmentHasher() {
    signal input bomb1_x;
    signal input bomb1_y;
    signal input bomb2_x;
    signal input bomb2_y;
    signal input bomb3_x;
    signal input bomb3_y;
    signal output commitment;
    component poseidonComponent;
    poseidonComponent = Poseidon(6);
    poseidonComponent.inputs[0] <== bomb1_x;
    poseidonComponent.inputs[1] <== bomb1_y;
    poseidonComponent.inputs[2] <== bomb2_x;
    poseidonComponent.inputs[3] <== bomb2_y;
    poseidonComponent.inputs[4] <== bomb3_x;
    poseidonComponent.inputs[5] <== bomb3_y;
    commitment <== poseidonComponent.out;
}

template detonateBomb() {
    signal input bomb1_x;
    signal input bomb1_y;
    signal input bomb2_x;
    signal input bomb2_y;
    signal input bomb3_x;
    signal input bomb3_y;
    signal input player_x;
    signal input player_y;
    signal output commitment;
    signal output result;

    component commitmentHasherComponent;
    commitmentHasherComponent = commitmentHasher();
    commitmentHasherComponent.bomb1_x <== bomb1_x;
    commitmentHasherComponent.bomb1_y <== bomb1_y;
    commitmentHasherComponent.bomb2_x <== bomb2_x;
    commitmentHasherComponent.bomb2_y <== bomb2_y;
    commitmentHasherComponent.bomb3_x <== bomb3_x;
    commitmentHasherComponent.bomb3_y <== bomb3_y;
    commitment <== commitmentHasherComponent.commitment;

    // Comparators
    signal check_bomb1_x, check_bomb1_y;
    signal check_bomb2_x, check_bomb2_y;
    signal check_bomb3_x, check_bomb3_y;

    check_bomb1_x <== bomb1_x - player_x;
    check_bomb1_y <== bomb1_y - player_y;
    check_bomb2_x <== bomb2_x - player_x;
    check_bomb2_y <== bomb2_y - player_y;
    check_bomb3_x <== bomb3_x - player_x;
    check_bomb3_y <== bomb3_y - player_y;

    // Check if any of the comparisons are zero
    component isz_bomb1_x = IsZero();
    component isz_bomb1_y = IsZero();
    component isz_bomb2_x = IsZero();
    component isz_bomb2_y = IsZero();
    component isz_bomb3_x = IsZero();
    component isz_bomb3_y = IsZero();

    isz_bomb1_x.in <== check_bomb1_x;
    isz_bomb1_y.in <== check_bomb1_y;
    isz_bomb2_x.in <== check_bomb2_x;
    isz_bomb2_y.in <== check_bomb2_y;
    isz_bomb3_x.in <== check_bomb3_x;
    isz_bomb3_y.in <== check_bomb3_y;

    // Aggregate results
    signal match_a, match_b, match_c;
    signal match_any;

    match_a <== isz_bomb1_x.out * isz_bomb1_y.out;
    match_b <== isz_bomb2_x.out * isz_bomb2_y.out;
    match_c <== isz_bomb3_x.out * isz_bomb3_y.out;

    match_any <== match_a + match_b + match_c;

    component isz_final = IsZero();
    isz_final.in <== 1 - match_any;
    isz_final.out ==> result;

    log(result);
    log(commitment);
}

component main {public [player_x, player_y]} = detonateBomb();

This circuit uses the Poseidon hash and the IsZero comparator libraries. You will need to install them as dependencies.



cd packages/zk/circuits
git clone https://github.com/iden3/circomlib.git

Now create an input file to test if everything works fine.

packages/zk/circuits/input.json



{
    "bomb1_x": 1,
    "bomb1_y": 1,
    "bomb2_x": 2,
    "bomb2_y": 2,
    "bomb3_x": 2,
    "bomb3_y": 3,
    "player_x": 2,
    "player_y": 3
}

Compile and generate a proof.



circom detonateBomb.circom --r1cs --wasm --sym
node detonateBomb_js/generate_witness.js detonateBomb_js/detonateBomb.wasm input.json witness.wtns

With the given input the result is equal to 1 because the player stepped into the 2,3 bomb. Also, the commitment is prompted on the terminal, copy paste it somewhere, we'll need it later on the tutorial.



Result:
1
Bombs commitment:
8613278371666841974523698252941148485158405612101680617360618409530277878563

We're using Groth16 for this demo, now run the trusted setup.



snarkjs powersoftau new bn128 12 pot12_0000.ptau -v
snarkjs powersoftau contribute pot12_0000.ptau pot12_0001.ptau --name="First contribution" -v
snarkjs powersoftau prepare phase2 pot12_0001.ptau pot12_final.ptau -v
snarkjs groth16 setup detonateBomb.r1cs pot12_final.ptau detonateBomb_0000.zkey
snarkjs zkey contribute detonateBomb_0000.zkey detonateBomb_0001.zkey --name="1st Contributor Name" -v
snarkjs zkey export verificationkey detonateBomb_0001.zkey verification_key.json
snarkjs zkey export solidityverifier detonateBomb_0001.zkey ../../contracts/src/CircomVerifier.sol

Finally, place the artifacts on the prover directory that will be used by the end of this tutorial.



cp detonateBomb_js/detonateBomb.wasm ../prover/zk_artifacts/
cp detonateBomb_0001.zkey ../prover/zk_artifacts/detonateBomb_final.zkey

3. Spawn, move and detonate bombs on Solidity

Go back to the project root.



cd ../../../

Remove non needed files.



rm packages/contracts/src/systems/IncrementSystem.sol packages/contracts/test/CounterTest.t.sol

The game system allows regular players to execute spawn and move and the Game Master to detonateBombs by passing as parameter a ZK proof. Notice we also emit an event when the player moves, this will become handy later on, when we build the ZK prover indexer.

packages/contracts/src/systems/MyGameSystem.sol



// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

import { System } from "@latticexyz/world/src/System.sol";
import { Player, PlayerData, ZKState } from "../codegen/index.sol";
import { Direction } from "../codegen/common.sol";
import { getKeysWithValue } from "@latticexyz/world-modules/src/modules/keyswithvalue/getKeysWithValue.sol";

import { EncodedLengths, EncodedLengthsLib } from "@latticexyz/store/src/EncodedLengths.sol";

interface ICircomVerifier {
    function verifyProof(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[4] calldata _pubSignals) external view returns (bool);
}

contract MyGameSystem is System {
  function spawn(int32 x, int32 y) public {
    address playerAddress = _msgSender();
    Player.set(playerAddress, x, y, false);
  }

  function move(Direction direction) public {
    address playerAddress = _msgSender();
    PlayerData memory player = Player.get(playerAddress);

    require(!player.isDead, "Player is dead");

    int32 x = player.x;
    int32 y = player.y;

    if(direction == Direction.Up)
      y-=1;
    if(direction == Direction.Down)
      y+=1;
    if(direction == Direction.Left)
      x-=1;
    if(direction == Direction.Right)
      x+=1;

    require(x>= -31 && x<= 31 && y>= -31 && y<= 31, "Invalid position");

    Player.setX(playerAddress, x);
    Player.setY(playerAddress, y);
  }

  function detonateBomb(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[4] calldata _pubSignals, address playerAddress) public {
    ICircomVerifier(ZKState.getCircomVerifier()).verifyProof(_pA, _pB, _pC, _pubSignals);
    uint32 commitment = uint32(_pubSignals[0]);
    uint32 result = uint32(_pubSignals[1]);
    int32 guessX = int32(uint32(uint(_pubSignals[2])));
    int32 guessY = int32(uint32(uint(_pubSignals[3])));

    PlayerData memory player = Player.get(playerAddress);

    require(!player.isDead, "Player already dead");
    require(result == 1, "No bomb in this position");
    require(player.x == guessX && player.y == guessY, "Invalid position ");

    uint32 bombsCommitment = ZKState.getBombsCommitment();
    require(uint32(uint(commitment)) == bombsCommitment, "Invalid commitment");

    Player.setIsDead(playerAddress, true);
  }
}

When deploying, the GM will need to store the bomb commitment on-chain so he can't change it later on. Also notice we deploy the Groth16Verifier contract that was generated on step 2.

packages/contracts/script/PostDeploy.s.sol



// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

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 { ZKState } from "../src/codegen/index.sol";
import { Groth16Verifier } from "../src/CircomVerifier.sol";

contract PostDeploy is Script {
  function run(address worldAddress) external {
    StoreSwitch.setStoreAddress(worldAddress);
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
    vm.startBroadcast(deployerPrivateKey);

    uint32 bombsCommitment = uint32(uint(8613278371666841974523698252941148485158405612101680617360618409530277878563));
    address circomVerifier = address(new Groth16Verifier());
    ZKState.set(bombsCommitment, circomVerifier);

    vm.stopBroadcast();
  }
}

4. Interact with the users via Phaser

Phaser is the game framework that facilitates animations, key presses, sounds, events. We define those on our Game System.

packages/client/src/layers/phaser/systems/myGameSystem.ts



import { Has, defineEnterSystem, defineSystem, defineExitSystem, getComponentValueStrict } from "@latticexyz/recs";
import { PhaserLayer } from "../createPhaserLayer";
import { 
  pixelCoordToTileCoord,
  tileCoordToPixelCoord
} from "@latticexyz/phaserx";
import { TILE_WIDTH, TILE_HEIGHT, Animations, Directions } from "../constants";

export const createMyGameSystem = (layer: PhaserLayer) => {
  const {
    world,
    networkLayer: {
      components: {
        Player
      },
      systemCalls: {
        spawn,
        move
      }
    },
    scenes: {
        Main: {
            objectPool,
            input
        }
    }
  } = layer;

  let toggle = false;

  input.pointerdown$.subscribe((event) => {
    const x = event.pointer.worldX;
    const y = event.pointer.worldY;
    const player = pixelCoordToTileCoord({ x, y }, TILE_WIDTH, TILE_HEIGHT);
    if(player.x == 0 && player.y == 0)
        return;
    spawn(player.x, player.y) 
  });

  input.onKeyPress((keys) => keys.has("W"), () => {
    move(Directions.UP);
  });

  input.onKeyPress((keys) => keys.has("S"), () => {
    move(Directions.DOWN);
  });

  input.onKeyPress((keys) => keys.has("A"), () => {
    move(Directions.LEFT);
  });

  input.onKeyPress((keys) => keys.has("D"), () => {
    move(Directions.RIGHT);
  });

  input.onKeyPress((keys) => keys.has("I"), () => {
    // This should not be on the client, just for demo purposes
    let bombSprite1 = objectPool.get("Bomb1", "Sprite");
    let bombSprite2 = objectPool.get("Bomb2", "Sprite");
    let bombSprite3 = objectPool.get("Bomb3", "Sprite");
    if (toggle == true) {
      bombSprite1.setComponent({
        id: "position",
        once: (sprite1) => {
          sprite1.setVisible(false);
        }
      })
      bombSprite2.setComponent({
        id: "position",
        once: (sprite2) => {
          sprite2.setVisible(false);
        }
      })
      bombSprite3.setComponent({
        id: "position",
        once: (sprite3) => {
          sprite3.setVisible(false);
        }
      })
    } else {
      bombSprite1.setComponent({
        id: 'animation',
        once: (sprite1) => {
          sprite1.setVisible(true);
          sprite1.play(Animations.Bomb);
          sprite1.setPosition(1*32, 1*32);
        }
      })
      bombSprite2.setComponent({
        id: 'animation',
        once: (sprite2) => {
          sprite2.setVisible(true);
          sprite2.play(Animations.Bomb);
          sprite2.setPosition(2*32, 2*32);
        }
      })
      bombSprite3.setComponent({
        id: 'animation',
        once: (sprite3) => {
          sprite3.setVisible(true);
          sprite3.play(Animations.Bomb);
          sprite3.setPosition(2*32, 3*32);
        }
      })
    }
    toggle = !toggle;
  });

  defineEnterSystem(world, [Has(Player)], ({entity}) => {
    const playerObj = objectPool.get(entity, "Sprite");
    playerObj.setComponent({
        id: 'animation',
        once: (sprite) => {
            sprite.play(Animations.Player);
        }
    })
  });

  defineSystem(world, [Has(Player)], ({ entity }) => {
    const player = getComponentValueStrict(Player, entity);
    const pixelPosition = tileCoordToPixelCoord(player, TILE_WIDTH, TILE_HEIGHT);

    const playerObj = objectPool.get(entity, "Sprite");


    if(player.isDead)
    {
        playerObj.setComponent({
            id: 'animation',
            once: (sprite) => {
              sprite.play(Animations.Dead);
            }
        })
    }

    playerObj.setComponent({
      id: "position",
      once: (sprite) => {
        sprite.setPosition(pixelPosition.x, pixelPosition.y);
      }
    })
  })
};

Now add the images on the sprites directory, separated by folder, with sequential names.

packages/art/sprites/player/1.png

packages/art/sprites/player/2.png

packages/art/sprites/bomb/1.png

packages/art/sprites/dead/1.png

And build the tileset.



cd packages/art
yarn
yarn generate-multiatlas-sprites

Finally, define the animation images, names, duration and behavior.

packages/client/src/layers/phaser/configurePhaser.ts



import Phaser from "phaser";
import {
  defineSceneConfig,
  AssetType,
  defineScaleConfig,
  defineMapConfig,
  defineCameraConfig,
} from "@latticexyz/phaserx";
import worldTileset from "../../../public/assets/tilesets/world.png";
import { TileAnimations, Tileset } from "../../artTypes/world";
import { Assets, Maps, Scenes, TILE_HEIGHT, TILE_WIDTH, Animations } from "./constants";

const ANIMATION_INTERVAL = 200;

const mainMap = defineMapConfig({
  chunkSize: TILE_WIDTH * 64, // tile size * tile amount
  tileWidth: TILE_WIDTH,
  tileHeight: TILE_HEIGHT,
  backgroundTile: [Tileset.Grass],
  animationInterval: ANIMATION_INTERVAL,
  tileAnimations: TileAnimations,
  layers: {
    layers: {
      Background: { tilesets: ["Default"] },
      Foreground: { tilesets: ["Default"] },
    },
    defaultLayer: "Background",
  },
});

export const phaserConfig = {
  sceneConfig: {
    [Scenes.Main]: defineSceneConfig({
      assets: {
        [Assets.Tileset]: {
          type: AssetType.Image,
          key: Assets.Tileset,
          path: worldTileset,
        },
        [Assets.MainAtlas]: {
          type: AssetType.MultiAtlas,
          key: Assets.MainAtlas,
          // Add a timestamp to the end of the path to prevent caching
          path: `/assets/atlases/atlas.json?timestamp=${Date.now()}`,
          options: {
            imagePath: "/assets/atlases/",
          },
        },
      },
      maps: {
        [Maps.Main]: mainMap,
      },
      sprites: {
      },
      animations: [
        {
          key: Animations.Player,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 2,
          frameRate: 3,
          repeat: -1,
          prefix: "sprites/player/",
          suffix: ".png",
        },
        {
          key: Animations.Dead,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 12,
          repeat: -1,
          prefix: "sprites/dead/",
          suffix: ".png",
        },
        {
          key: Animations.Bomb,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 12,
          repeat: -1,
          prefix: "sprites/bomb/",
          suffix: ".png",
        },
      ],
      tilesets: {
        Default: {
          assetKey: Assets.Tileset,
          tileWidth: TILE_WIDTH,
          tileHeight: TILE_HEIGHT,
        },
      },
    }),
  },
  scale: defineScaleConfig({
    parent: "phaser-game",
    zoom: 1,
    mode: Phaser.Scale.NONE,
  }),
  cameraConfig: defineCameraConfig({
    pinchSpeed: 1,
    wheelSpeed: 1,
    maxZoom: 3,
    minZoom: 1,
  }),
  cullingChunkSize: TILE_HEIGHT * 16,
};

5. Bind everything together

Setup all the variables and functions that the client needs in order to have visibility of web3 functions defined on the contracts.

packages/client/src/layers/phaser/constants.ts



export enum Scenes {
  Main = "Main",
}

export enum Maps {
  Main = "Main",
}

export enum Animations {
  Player = "Player",
  Dead = "Dead",
  Bomb = "Bomb",
}

export enum Directions {
  UP = 0,  
  DOWN = 1,  
  LEFT = 2,  
  RIGHT = 3,  
}

export enum Assets {
  MainAtlas = "MainAtlas",
  Tileset = "Tileset",
}

export const TILE_HEIGHT = 32;
export const TILE_WIDTH = 32;

packages/client/src/layers/phaser/systems/registerSystems.ts



import { PhaserLayer } from "../createPhaserLayer";
import { createCamera } from "./createCamera";
import { createMapSystem } from "./createMapSystem";
import { createMyGameSystem } from "./myGameSystem";

export const registerSystems = (layer: PhaserLayer) => {
  createCamera(layer);
  createMapSystem(layer);
  createMyGameSystem(layer);
};

packages/client/src/mud/createSystemCalls.ts



import { getComponentValue } from "@latticexyz/recs";
import { ClientComponents } from "./createClientComponents";
import { SetupNetworkResult } from "./setupNetwork";
import { singletonEntity } from "@latticexyz/store-sync/recs";

export type SystemCalls = ReturnType<typeof createSystemCalls>;

export function createSystemCalls(
  { worldContract, waitForTransaction }: SetupNetworkResult,
  { Player }: ClientComponents,
) {
  const spawn = async (x: number, y: number) => {
    const tx = await worldContract.write.app__spawn([x, y]);
    await waitForTransaction(tx);
    return getComponentValue(Player, singletonEntity);
  };

  const move = async (direction: number) => {
    const tx = await worldContract.write.app__move([direction]);
    await waitForTransaction(tx);
    return getComponentValue(Player,  singletonEntity);
  }

  return {
    spawn, move
  };
}

We're ready now to launch the server. Go back to the root folder and deploy it.



cd ../../
pnpm dev

6. Run the prover backend

MUD has its own logging system (known as events in Solidity) where it emits a Store_SetRecord by default every time a record is modified. This is very convenient for us because the tester will listen to all player movement events on-chain, and when it detects that a player has come into contact with a bomb, it will detonate it. This is possible because only the tester has knowledge of the hidden bombs.

Let's start by creating a new npm project and installing the dependencies.



cd packages/zk/prover/
npm init -y
npm install express ethers snarkjs

Now create your server logic node file. We'll use a very simple express server, ethersjs will take care of all the web3 requirements and snarkjs will produce the proofs.

packages/zk/prover/server.js



const express = require('express');
const { ethers } = require('ethers');
const fs = require('fs');
const snarkjs = require('snarkjs');

const contractAddressWorld = "0x8d8b6b8414e1e3dcfd4168561b9be6bd3bf6ec4b";
const privateKey = "0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80";
const playerTableId = "0x74626170700000000000000000000000506c6179657200000000000000000000";

const bombPositions = JSON.parse(fs.readFileSync('bombs.json', 'utf-8'));

const app = express();
const PORT = 8080;

const provider = new ethers.JsonRpcProvider('http://localhost:8545');
const contractABI = [
    "function detonateBomb(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[4] calldata _pubSignals, address playerAddress)",
];

const contractABIWorld = [
    "event Store_SetRecord(bytes32 indexed tableId, bytes32[] keyTuple, bytes staticData, bytes32 encodedLengths, bytes dynamicData)",
    "function app__detonateBomb(uint[2] calldata _pA, uint[2][2] calldata _pB, uint[2] calldata _pC, uint[4] calldata _pubSignals, address playerAddress)"
];

const wallet = new ethers.Wallet(privateKey, provider);
const contractWorld = new ethers.Contract(contractAddressWorld, contractABIWorld, wallet);


function decodeRecord(hexString) {
    if (hexString.startsWith('0x')) {
        hexString = hexString.slice(2);
    }
    const xHex = hexString.slice(0, 8);
    const yHex = hexString.slice(8, 16);
    const isDeadHex = hexString.slice(16, 18);
    const x = parseInt(xHex, 16) | 0;
    const y = parseInt(yHex, 16) | 0;
    const isDead = parseInt(isDeadHex, 16) != 0;
    return { x, y, isDead };
}

contractWorld.on("Store_SetRecord", async (tableId, keyTuple, staticData, encodedLengths, dynamicData) => {
    if(tableId == playerTableId)
    {
        let decodedRecord = decodeRecord(staticData);
        let player = '0x' + keyTuple[0].replace(/^0x000000000000000000000000/, '');

        if(!decodedRecord.isDead)
        {
            await detonateBomb(player, decodedRecord.x, decodedRecord.y);
        }
    }
});

async function detonateBomb(player, x, y) {
    console.log(`Player move to (${x}, ${y})`);
    for (const bomb of bombPositions) {
        if (""+bomb.x === ""+x && ""+bomb.y === ""+y) {
            try {
                const { proof, publicSignals } = await snarkjs.groth16.fullProve(
                    {
                        bomb1_x: bombPositions[0].x,
                        bomb1_y: bombPositions[0].y,
                        bomb2_x: bombPositions[1].x,
                        bomb2_y: bombPositions[1].y,
                        bomb3_x: bombPositions[2].x,
                        bomb3_y: bombPositions[2].y,
                        player_x: x,
                        player_y: y
                    },
                    "./zk_artifacts/detonateBomb.wasm",
                    "./zk_artifacts/detonateBomb_final.zkey"
                );

                let pA = proof.pi_a;
                pA.pop();
                let pB = proof.pi_b;
                pB.pop();
                let pC = proof.pi_c;
                pC.pop();

                if (publicSignals[1] == "1") {
                    const tx = await contractWorld.app__detonateBomb(
                        pA,
                        pB,
                        pC,
                        publicSignals,
                        player
                    );
                    console.log('Transaction:', tx);
                }
            } catch (error) {
                console.error("Error generating or verifying proof:", error);
            }
        }
    }
}

app.get('/', (req, res) => {
    res.send('Server is running');
});

app.listen(PORT, async () => {
    console.log(`Server is listening on port ${PORT}`);
});

Notice you will need your Player table tableId. Grab it from the ui.

The private bombs data will be stored in a separate json file.

packages/zk/prover/bombs.json



[
    {"x": 1, "y": 1},
    {"x": 2, "y": 2},
    {"x": 2, "y": 3}
]

To run your prover backend, you will need the MyGameSystem and World address, also a private key of a wallet with ETH.

Grab the World address from your contract process after it finishes loading. Put it on the CONTRACT_ADDRESS_WORLD environment variable.

Setup the contractAddressWorld and playerTableId variables now.

You are ready to start the prover now.



node server.js

If a player steps into a bomb the prover will detect it and detonate tbe bomb on-chain.

Going forward

If you are familiarized with on chain gaimming you might be wondering: Isn't a minesweeper game possible with a traditional commit-reveal scheme? And yes, that's correct, you can do a minesweeper by commiting to the bombs positions on a, for example, mapping(uint bombId => bytes32 commitment). However, while some commit-reveal complications can be solved by themselves, like for example apply modulus % to the commitment to prevent brute force attacks, ZK introduces new capabilities where I see a lot of potential. Here I share some so you can get inspired by having a sense some of the posibilities.

1. Constrained commitments

When you post a normal commit there is no way of applying constraints to it. On ZK you can, for example define the boundaries of a map, be specific about the amount and caracteristics of the hidden data. For example, there is higher chance to find ore in the mountains or fish in a river. All of this can be defined on the circuit.

2. Data optimizations

ZK allows to reveal portions of a commitment. This means a smaller amount of data is posted on-chain. Yes, verifying zk proofs is expensive at execution level but on L2s execution is cheap and data is expensive, even with danksharding and plasma. That's why cheap execution environments such as Redstone are ideal for this type of games if you are ok with sacrificing a bit of security.

3. More ZK constructions

In this tutorial we went through a PvE scenario, where a player interacts with an environment in adversarial situations. Where all the private off-chain computation is provable and secured on-chain. Now imagine PvP scenarios, or other ZK constructions applied to other types of games.

On future guides I would like to explore other ZK constructions such as private item consuption or private actions by posting merkle inclusion proofs. So stay tuned!

Thanks for reading this guide!

Follow Filosofía Código on dev.to and in Youtube for everything related to Blockchain development.

How to create an Autonomous World Game

Ahmed Castro — Mon, 29 Jul 2024 15:14:59 +0000

MUD started as a framework for creating 100% on-chain games, but now it is much more than that. In addition to creating interactive games with smart contract mechanics, MUD is a tool capable of creating autonomous worlds. What is an autonomous world? This goes beyond finance and games; in these worlds, you can create simulations where artificial intelligence is first-class citizens. If this sounds pretty crazy, it’s because it is.

To learn more about MUD, let’s start by creating a game where characters collect coins. In this guide, we will do everything from scratch. We’ll create the contracts, the project structure, and the animations.

Create a New MUD Project

We’ll be using Node v20 (>=18 should be ok), pnpm, and Foundry. If you don’t have them installed, here are the commands.

Dependency installation

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20
curl -L https://foundry.paradigm.xyz | bash export PATH=$PATH:~/.foundry/bin
sudo npm install -g pnpm

Once the dependencies are installed, you can create a new MUD project.

pnpm create mud@latest tutorial
cd tutorial

During the installation process, select a Phaser project.

1. The State Schema

This is the most important file in MUD; it defines the data structure of the state of your contracts. In MUD, you don't declare state variables like mapping, uint, bool, etc., nor do you use enum. Instead, you define them in the file below.

packages/contracts/mud.config.ts

import { defineWorld } from "@latticexyz/world";

export default defineWorld({
  namespace: "app",
  enums: {
    Direction: [
      "Up",
      "Down",
      "Left",
      "Right"
    ]
  },
  tables: {
    PlayerPosition: {
      schema: {
        player: "address",
        x: "int32",
        y: "int32",
      },
      key: ["player"]
    },
    CoinPosition: {
      schema: {
        x: "int32",
        y: "int32",
        exists: "bool",
      },
      key: ["x", "y"]
    },
    PlayerCoins: {
      schema: {
        player: "address",
        amount: "uint32",
      },
      key: ["player"]
    }
  }
});

2. Logic in Solidity

The logic for functions in MUD is the same as in a regular Solidity project. Declare your view, payable, pure functions with modifiers and everything else just as you’re used to.

So, delete the default logic and create the game logic that validates when a player moves and collects coins.

Delete packages/contracts/src/systems/IncrementSystem.sol that comes by default. You only need to do this if you’re using the vanilla, react-ecs, or phaser templates provided by MUD.

rm packages/contracts/src/systems/IncrementSystem.sol packages/contracts/test/CounterTest.t.sol

packages/contracts/src/systems/MyGameSystem.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

import { System } from "@latticexyz/world/src/System.sol";
import { PlayerPosition, PlayerPositionData, CoinPosition, PlayerCoins } from "../codegen/index.sol";
import { Direction } from "../codegen/common.sol";
import { getKeysWithValue } from "@latticexyz/world-modules/src/modules/keyswithvalue/getKeysWithValue.sol";

import { EncodedLengths, EncodedLengthsLib } from "@latticexyz/store/src/EncodedLengths.sol";

contract MyGameSystem is System {
  function generateCoins() public {
    CoinPosition.set(1, 1, true);
    CoinPosition.set(2, 2, true);
    CoinPosition.set(2, 3, true);
  }

  function spawn(int32 x, int32 y) public {
    address player = _msgSender();
    PlayerPosition.set(player, x, y);
  }

  function move(Direction direction) public {
    address player = _msgSender();
    PlayerPositionData memory playerPosition = PlayerPosition.get(player);

    int32 x = playerPosition.x;
    int32 y = playerPosition.y;

    if(direction == Direction.Up)
      y-=1;
    if(direction == Direction.Down)
      y+=1;
    if(direction == Direction.Left)
      x-=1;
    if(direction == Direction.Right)
      x+=1;

    require(x>= -31 && x<= 31 && y>= -31 && y<= 31, "Invalid position");

    PlayerPosition.set(player, x, y);

    if(CoinPosition.getExists(x, y))
    {
      CoinPosition.set(x, y, false);
      PlayerCoins.set(player, PlayerCoins.getAmount(player)+1);
    }
  }
}

Actually, not all functions operate the same way as in a vanilla Solidity project. If you try, you’ll notice that the constructor doesn’t work as expected. This is because Systems are designed to operate without a specific state. This means that a single System can operate with multiple Worlds, which are responsible for managing the state. This is why we put all the initialization logic in the post-deploy contract.

In our case, we place certain coins on the map.

packages/contracts/script/PostDeploy.s.sol

// SPDX-License-Identifier: MIT
pragma solidity >=0.8.24;

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";

contract PostDeploy is Script {
  function run(address worldAddress) external {
    StoreSwitch.setStoreAddress(worldAddress);
    uint256 deployerPrivateKey = vm.envUint("PRIVATE_KEY");
    vm.startBroadcast(deployerPrivateKey);

    IWorld(worldAddress).app__generateCoins();

    vm.stopBroadcast();
  }
}

3. Client Interaction

The client contains all the off-chain logic. This is where we define what is displayed on the screen and also what happens when the user clicks or presses a key.

packages/client/src/layers/phaser/systems/myGameSystem.ts

import { Has, defineEnterSystem, defineSystem, defineExitSystem, getComponentValueStrict } from "@latticexyz/recs";
import { PhaserLayer } from "../createPhaserLayer";
import { 
  pixelCoordToTileCoord,
  tileCoordToPixelCoord
} from "@latticexyz/phaserx";
import { TILE_WIDTH, TILE_HEIGHT, Animations, Directions } from "../constants";

function decodeHexString(hexString: string): [number, number] {
  const cleanHex = hexString.slice(2);
  const firstHalf = cleanHex.slice(0, cleanHex.length / 2);
  const secondHalf = cleanHex.slice(cleanHex.length / 2);
  return [parseInt(firstHalf, 16), parseInt(secondHalf, 16)];
}

export const createMyGameSystem = (layer: PhaserLayer) => {
  const {
    world,
    networkLayer: {
      components: {
        PlayerPosition,
        CoinPosition
      },
      systemCalls: {
        spawn,
        move,
        generateCoins
      }
    },
    scenes: {
        Main: {
            objectPool,
            input
        }
    }
  } = layer;

  input.pointerdown$.subscribe((event) => {
    const x = event.pointer.worldX;
    const y = event.pointer.worldY;
    const playerPosition = pixelCoordToTileCoord({ x, y }, TILE_WIDTH, TILE_HEIGHT);
    if(playerPosition.x == 0 && playerPosition.y == 0)
        return;
    spawn(playerPosition.x, playerPosition.y) 
  });

  input.onKeyPress((keys) => keys.has("W"), () => {
    move(Directions.UP);
  });

  input.onKeyPress((keys) => keys.has("S"), () => {
    move(Directions.DOWN);
  });

  input.onKeyPress((keys) => keys.has("A"), () => {
    move(Directions.LEFT);
  });

  input.onKeyPress((keys) => keys.has("D"), () => {
    move(Directions.RIGHT);
  });

  input.onKeyPress((keys) => keys.has("I"), () => {
    generateCoins();
  });

  defineEnterSystem(world, [Has(PlayerPosition)], ({entity}) => {
    const playerObj = objectPool.get(entity, "Sprite");
    playerObj.setComponent({
        id: 'animation',
        once: (sprite) => {
            sprite.play(Animations.Player);
        }
    })
  });

  defineEnterSystem(world, [Has(CoinPosition)], ({entity}) => {
    const coinObj = objectPool.get(entity, "Sprite");
    coinObj.setComponent({
        id: 'animation',
        once: (sprite) => {
          sprite.play(Animations.Coin);
        }
    })
  });

  defineSystem(world, [Has(PlayerPosition)], ({ entity }) => {
    const playerPosition = getComponentValueStrict(PlayerPosition, entity);
    const pixelPosition = tileCoordToPixelCoord(playerPosition, TILE_WIDTH, TILE_HEIGHT);

    const playerObj = objectPool.get(entity, "Sprite");

    playerObj.setComponent({
      id: "position",
      once: (sprite) => {
        sprite.setPosition(pixelPosition.x, pixelPosition.y);
      }
    })
  })

  defineSystem(world, [Has(CoinPosition)], ({ entity }) => {
    const [coinX, coinY] = decodeHexString(entity);

    const coinExists = getComponentValueStrict(CoinPosition, entity).exists;
    const pixelPosition = tileCoordToPixelCoord({x: coinX, y: coinY}, TILE_WIDTH, TILE_HEIGHT);

    const coinObj = objectPool.get(entity, "Sprite");

    if(coinExists) {
      coinObj.setComponent({
        id: "position",
        once: (sprite) => {
          sprite.setPosition(pixelPosition.x, pixelPosition.y);
        }
      })
    }else
    {
      objectPool.remove(entity);
    }
  })
};

4. Add Images and Animations

If you want to add an animated object, place it in its own folder under packages/art/sprites/. Ensure that the animation frames are named sequentially, such as 1.png, 2.png, 3.png, etc.

In our case, we will add 2 images for our character and one for the coins.

packages/art/player/1.png

packages/art/player/2.png

packages/art/coin/1.png

Next, run the following commands to automate the packaging of your files into sprite sheets.

cd packages/art
yarn
yarn generate-multiatlas-sprites

In the Phaser file, you can configure the speed and name of the animations. Here, you can also define attributes that you can use in your system.

packages/client/src/layers/phaser/configurePhaser.ts

import Phaser from "phaser";
import {
  defineSceneConfig,
  AssetType,
  defineScaleConfig,
  defineMapConfig,
  defineCameraConfig,
} from "@latticexyz/phaserx";
import worldTileset from "../../../public/assets/tilesets/world.png";
import { TileAnimations, Tileset } from "../../artTypes/world";
import { Assets, Maps, Scenes, TILE_HEIGHT, TILE_WIDTH, Animations } from "./constants";

const ANIMATION_INTERVAL = 200;

const mainMap = defineMapConfig({
  chunkSize: TILE_WIDTH * 64, // tile size * tile amount
  tileWidth: TILE_WIDTH,
  tileHeight: TILE_HEIGHT,
  backgroundTile: [Tileset.Grass],
  animationInterval: ANIMATION_INTERVAL,
  tileAnimations: TileAnimations,
  layers: {
    layers: {
      Background: { tilesets: ["Default"] },
      Foreground: { tilesets: ["Default"] },
    },
    defaultLayer: "Background",
  },
});

export const phaserConfig = {
  sceneConfig: {
    [Scenes.Main]: defineSceneConfig({
      assets: {
        [Assets.Tileset]: {
          type: AssetType.Image,
          key: Assets.Tileset,
          path: worldTileset,
        },
        [Assets.MainAtlas]: {
          type: AssetType.MultiAtlas,
          key: Assets.MainAtlas,
          // Add a timestamp to the end of the path to prevent caching
          path: `/assets/atlases/atlas.json?timestamp=${Date.now()}`,
          options: {
            imagePath: "/assets/atlases/",
          },
        },
      },
      maps: {
        [Maps.Main]: mainMap,
      },
      sprites: {
      },
      animations: [
        {
          key: Animations.Player,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 2,
          frameRate: 3,
          repeat: -1,
          prefix: "sprites/player/",
          suffix: ".png",
        },
        {
          key: Animations.Coin,
          assetKey: Assets.MainAtlas,
          startFrame: 1,
          endFrame: 1,
          frameRate: 12,
          repeat: -1,
          prefix: "sprites/coin/",
          suffix: ".png",
        },
      ],
      tilesets: {
        Default: {
          assetKey: Assets.Tileset,
          tileWidth: TILE_WIDTH,
          tileHeight: TILE_HEIGHT,
        },
      },
    }),
  },
  scale: defineScaleConfig({
    parent: "phaser-game",
    zoom: 1,
    mode: Phaser.Scale.NONE,
  }),
  cameraConfig: defineCameraConfig({
    pinchSpeed: 1,
    wheelSpeed: 1,
    maxZoom: 3,
    minZoom: 1,
  }),
  cullingChunkSize: TILE_HEIGHT * 16,
};

5. Bind everything together

Perhaps in the future, MUD will automate a couple of functions that you need to connect manually. This allows the client package to connect to the contracts.

packages/client/src/layers/phaser/constants.ts

export enum Scenes {
  Main = "Main",
}

export enum Maps {
  Main = "Main",
}

export enum Animations {
  Player = "Player",
  Coin = "Coin",
}

export enum Directions {
  UP = 0,  
  DOWN = 1,  
  LEFT = 2,  
  RIGHT = 3,  
}

export enum Assets {
  MainAtlas = "MainAtlas",
  Tileset = "Tileset",
}

export const TILE_HEIGHT = 32;
export const TILE_WIDTH = 32;

packages/client/src/mud/createSystemCalls.ts

import { getComponentValue } from "@latticexyz/recs";
import { ClientComponents } from "./createClientComponents";
import { SetupNetworkResult } from "./setupNetwork";
import { singletonEntity } from "@latticexyz/store-sync/recs";

export type SystemCalls = ReturnType<typeof createSystemCalls>;

export function createSystemCalls(
  { worldContract, waitForTransaction }: SetupNetworkResult,
  { PlayerPosition, CoinPosition }: ClientComponents,
) {
  const spawn = async (x: number, y: number) => {
    const tx = await worldContract.write.app__spawn([x, y]);
    await waitForTransaction(tx);
    return getComponentValue(PlayerPosition, singletonEntity);
  };

  const move = async (direction: number) => {
    const tx = await worldContract.write.app__move([direction]);
    await waitForTransaction(tx);
    return getComponentValue(PlayerPosition,  singletonEntity);
  }

  const generateCoins = async (direction: number) => {
    const tx = await worldContract.write.app__generateCoins();
    await waitForTransaction(tx);
    return getComponentValue(PlayerPosition,  singletonEntity);
  }
  return {
    spawn, move, generateCoins
  };
}

packages/client/src/layers/phaser/systems/registerSystems.ts

import { PhaserLayer } from "../createPhaserLayer";
import { createCamera } from "./createCamera";
import { createMapSystem } from "./createMapSystem";
import { createMyGameSystem } from "./myGameSystem";

export const registerSystems = (layer: PhaserLayer) => {
  createCamera(layer);
  createMapSystem(layer);
  createMyGameSystem(layer);
};

6. Run the Game

MUD has a hot reload system. This means that when you make a change in the game, it is detected, and the game reloads, applying the changes. This applies to both the client and the contracts.

pnpm dev

Move with WASD, touch the coins to collect them. The game is multiplayer online by default!

Thanks for reading this guide!

Follow Filosofía Código on dev.to and in Youtube for everything related to Blockchain development.

DEV Community: Filosofía Código EN

How Local Storage Wallets on Ethereum Work

What Is a Local Storage Wallet?

Why Use a Local Storage Wallet?

Is It Safe?

How Does It Work on realtimeplay.xyz?

What Happens If I Refresh or Close My Browser?

How to Create a Secure Telegram Bot🔒 with EIP-712

1. Create a New Telegram Bot

2. Launch the Telegram Bot Backend

3. Create a Web dApp to Sign Messages

4. Test Your Bot

Next Steps

One-click Loans on Aave with EIP-7702

How to Get a Loan on Aave

Temporarily Turn Your Wallet into a Smart Contract

Deploy the Multicall7702 Contract

Delegate Your Wallet to Multicall7702

Build the Frontend

Test Your dApp

Intro to Programatic Loans in Morpho

Monolithic vs. Multi‑Market Lending

The Morpho API

Market parameters

Solidity Implementation

How to Use

How to make an Ethereum Real-Time dApp with no Spaghetti code

Unruggable AI Agents with ZKML

Why Zero Knowledge?

Building a Verifiable Tipper AI Agent

In this tutorial, you’ll learn how to:

EZKL: ZKML library for developers

Step 0: Generate an AI model

Step 1: Create a Verifier Contract

Step 2: Generate a ZK Proof

Step 3. Launch the Tip Token

Step 4: Build the Tipper Contract

Next steps

A Brief History of zkVMs

From Low-Level Libraries to zkVMs

zkVMs today

How zkVMs Generate Value

Will zkDSLs Die?

Is There Competition in the zkVM Space?

Risc Zero

SP1

OpenVM

Conclusion

L1SLOAD: Reading Arrays, Structs and Nested Mappings

Static Arrays

Dynamic Arrays

Special Case: Storing Values 16 Bytes or Smaller

Structs

Nesting Structures

Next steps

Big Handmade Maps 100% On-Chain. Is it Possible?

Starting with the Theory

Naive Implementation: Avoid this 🙅

Merkleizing a Map

Why Merkleize a Map?

In practice: Creating a big map on MUD

The data

The table

The contract

The client

The map interpreter

The Client: User interaction and Merkle Proofs generation

The Animations, System Calls and Registration

Run the game

Closing thoughts

Encoding expressive worlds

Only submit proofs once

Bigger maps require Web2 optimizations

How to create an Information Asymmetric Autonomous World: MUD + Circom

Table of contents

The game

Create a MUD project

1. Define the State

2. Create the combat circuits

a. Attack SNARK