readme.md

📦 Smart Storage Unit Example

Build a vending machine for trading items using a Smart Storage Unit

Table of Contents

1. Introduction
2. Deployment and Testing in Local Environment
3. Deployment To The Game (Stillness)
4. Configuring and Testing the Game Contracts (Stillness)
5. Troubleshooting

Introduction

This example will show you how to deploy and configure smart contracts for a Smart Storage Unit that will trade items between the owner and other players. The amount traded is set by providing a ratio of items.

Before starting make sure you've installed all required tools from the main README

You can test everything locally first using the Local Environment Guide, and when ready, deploy to the live game using the Deployment Guide.

Additional Information

For additional details on the Smart Storage Unit, see our Documentation.

Deployment and Testing in Local Environment

To deploy the example to your local world hosted on Docker, follow the below steps.

Step 1: Deploy the example contracts to the existing world

First, copy the World Contract Address from the Docker logs obtained in the previous steps:

Then, run the following commands:

1. Navigate to the example directory:

   cd smart-storage-unit

2. Install the Solidity dependencies for the contracts:

   pnpm install

3. Create your environment file:

   cp packages/contracts/.envsample packages/contracts/.env

4. Deploy to your local test environment

   pnpm dev

Note

This will deploy the contracts to a forked version of your local world for testing.

Once the contracts have been deployed you should see the below message. When changing the contracts it will automatically re-deploy them.

Step 2: Setup the environment variables (Optional)

Next, update your .env file with the trade ratio:

#Item Bought
IN_RATIO=1
#Item Sold  
OUT_RATIO=2

Note

Trading Ratio Example: With the above ratio (1:2), when a player deposits 1 item, they receive 2 items in return.

Warning

Choose your ratios carefully to avoid accidentally depleting your item supply!

Step 3: Mock data for the existing world (Local Development Only)

Generate the test data by:

1. Select the "shell" process and then click on the main terminal window.

2. To generate mock data for testing the SSU logic on the local world, run the following command. This generates and deploys the smart storage deployable and items.

pnpm mock-data

Note

This will create the on-chain SSU, fuel it and bring it online.

Step 4: Configure SSU

To configure which items should be traded and the ratio's to trade for run:

pnpm configure

Note

You can adjust the values for the SSU_ID, in and out item ID's and the ratios in the .env file as needed, though they are optional to change for local development.

Step 5: Test The SSU (Optional)

To test the SSU, execute the following command which will run a series of pre-defined tests to ensure the contracts are working:

pnpm execute

Deployment to The Game (Stillness)

To deploy the example to the game server which is named Stillness, follow the below steps.

Step 1: Setup your Environment

Move to the example directory with:

cd smart-storage-unit/packages/contracts

Then install the Solidity dependencies for the contracts:

pnpm install

Then, if you haven't already copy the .envsample file to a .env file with:

cp .envsample .env

Step 2: Configure the Example to use Stillness

Next, set the following values in the .env file to direct the scripts to use Stillness:

WORLD_ADDRESS=0xcdb380e0cd3949caf70c45c67079f2e27a77fc47
RPC_URL=https://pyrope-external-sync-node-rpc.live.tech.evefrontier.com
CHAIN_ID=695569

You can also automatically point to Stillness with current values using:

pnpm env-stillness

Step 3: Configure the Namespace

A namespace is a unique identifier for deploying your smart contracts. Once you deploy to a namespace, it will set you as the owner and only you will be able to deploy smart contracts within the namespace.

Namespace Rules:

• ✅ Use letters (a-z, A-Z)
• ✅ Use numbers (0-9)
• ✅ Use underscores (_)
• ❌ No special characters
• ❌ No spaces

Change the namespace from test to your own custom namespace.

Tip

Consider using your username or corporation name as your namespace.

First, edit packages/contracts/mud.config.ts to include your new namespace:

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

export default defineWorld({
    namespace: "new_namespace",
    tables: {
        ...

Then, edit packages/contracts/src/systems/constants.sol:

bytes14 constant DEPLOYMENT_NAMESPACE = "new_namespace";

You can also use the below command and then input your new namespace to change it automatically:

pnpm set-namespace

Step 4: Configure the Private Key

Import your game wallet recovery phrase into EVE Wallet to get your private key:

Then, set the PRIVATE_KEY in your .env file:

PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

You can also use the below command and then input your private key to change it:

pnpm set-key

Step 5: Deploy the Contract

Then deploy the SSU contracts using:

pnpm run deploy:pyrope

Once the deployment is successful, you'll see a screen similar to the one below.

Configuring and Testing the Game Contracts (Stillness)

Step 1: Setup the environment variables

Next, replace the following values in the .env file with the below steps.

Step 1.1: Player Test Account (Optional)

Set the TEST_PLAYER_PRIVATE_KEY in your .env file to the private key of the account you want to test trades with which will be used by the execute script:

TEST_PLAYER_PRIVATE_KEY=0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

Note

This is only for testing, and an example not requiring this is on it's way.

Step 1.2: Smart Storage Unit ID (SSU ID)

For Stillness, the Smart Storage Unit ID (SSU ID) is available once you have deployed an SSU in the game.

1. Right click your Smart Storage Unit and press Interact

2. Copy the smart storage unit id.

3. Set the SSU_ID in the .env file.

   SSU_ID=34818344039668088032259299209624217066809194721387714788472158182502870248994

Step 1.3: Item ID's

To retrieve the Item ID's you can use https://world-api-stillness.live.tech.evefrontier.com/v2/types and then search for the item name.

You can use the "smartItemId" as the Item ID.

Example Response:

"83839": {
    "name": "Salt",
    "smartItemId": "70505200487489129491533272716910408603753256595363780714882065332876101173161"
}

Configure the Item ID's in the .env file.

#Item Bought
ITEM_IN_TYPE_ID=70505200487489129491533272716910408603753256595363780714882065332876101173161
#Item Sold
ITEM_OUT_TYPE_ID=112603025077760770783264636189502217226733230421932850697496331082050661822826

Step 1.4: Ratios

A ratio of 1:2 means the Smart Storage Unit will give players 2 items for every 1 item they deposit.

#Item Bought
IN_RATIO=1
#Item Sold
OUT_RATIO=2

Warning

Note: Be careful not to accidentally give away your whole supply of items with the wrong ratio.

---

You can also set these values automatically using the below command:

pnpm set-config

Step 2: Configure SSU

To configure which items should be traded and the ratio's to trade for run:

pnpm configure

Note

You can adjust the values for the SSU_ID, in and out item ID's and the ratios in the .env file as needed.

Important

Trades are not automatic, which means that you need to run the pnpm execute command or call the execute smart contract function on the SSU to trade items.

Step 3: Execute the trade

To trade items, make sure the items are in the inventories and then you need to run:

pnpm execute

Troubleshooting

If you encounter any issues, refer to the troubleshooting tips below:

1. World Address Mismatch: Double-check that the WORLD_ADDRESS is correctly updated in the contracts/.env file to ensure you are deploying contracts to the correct world.

2. Anvil Instance Conflicts: Ensure there is only one running instance of Anvil. The active instance should be initiated via the docker compose up -d command. Multiple instances of Anvil may cause unexpected behavior or deployment errors.

3. Trade Quantity Is Incorrect: Ensure your input and output ratios have been correctly set in the contracts/.env file.

4. The Trade is not Working: Ensure the ITEM_IN_TYPE_ID and ITEM_OUT_TYPE_ID are correctly set in the contracts/.env file.

Need Help?

If you are still having issues, then visit the Documentation or join the Discord Community for support.