Nethereum.Mud.Contracts 7.0.0

Nethereum.Mud.Contracts

Nethereum.Mud.Contracts provides contract definitions and services for interacting with MUD (Onchain Engine) World and Store contracts. It enables you to call MUD systems, query tables, and process Store events.

Features

• World Service - Interact with MUD World contract
• Store Services - Query and subscribe to Store events
• Table Services - Type-safe table query and mutation
• System Services - Call MUD system functions
• Event Processing - Process Store_SetRecord, Store_DeleteRecord, Store_SpliceStaticData, Store_SpliceDynamicData events
• Batch Calls - Efficient multi-call execution
• Access Control - Manage World permissions

Installation

dotnet add package Nethereum.Mud.Contracts

Dependencies

• Nethereum.Mud
• Nethereum.Web3

Key Concepts

World Contract

The World contract is the central registry for all MUD resources:

• Contains all namespaces, tables, and systems
• Provides call and callFrom for system execution
• Manages access control via grantAccess and revokeAccess
• Emits Store events for all state changes

Store Contract

The Store is embedded in the World and manages table data:

• Stores all table records as key-value pairs
• Emits events when data changes (Store_SetRecord, Store_DeleteRecord)
• Handles dynamic data via Store_SpliceStaticData and Store_SpliceDynamicData
• Provides schema registration via Tables table

Store Events

MUD emits events for all state changes:

Store_SetRecord

• Emitted when a table record is created or updated
• Contains: tableId, keyTuple, staticData, encodedLengths, dynamicData

Store_DeleteRecord

• Emitted when a table record is deleted
• Contains: tableId, keyTuple

Store_SpliceStaticData

• Emitted when static data is partially updated
• Contains: tableId, keyTuple, start, data

Store_SpliceDynamicData

• Emitted when dynamic data (arrays, strings) is partially updated
• Contains: tableId, keyTuple, dynamicFieldIndex, start, deleteCount, encodedLengths, data

Table Services

Generated table services provide type-safe access to MUD tables:

• Query records by key
• Query all records
• Decode table schemas
• Built on top of World contract

System Services

Generated system services wrap MUD system functions:

• Type-safe function calls
• Automatic ABI encoding
• Integration with World's call or direct system calls

World Contract Interaction

WorldService

The WorldService provides methods for interacting with the World contract:

public class WorldService
{
    // Call a system
    Task<TransactionReceipt> CallRequestAndWaitForReceiptAsync(
        byte[] systemId,
        byte[] callData
    );

    // Call a system with delegator
    Task<TransactionReceipt> CallFromRequestAndWaitForReceiptAsync(
        string delegator,
        byte[] systemId,
        byte[] callData
    );
}

// Access control (AccessManagementSystemService)
public class AccessManagementSystemService
{
    Task<TransactionReceipt> GrantAccessRequestAndWaitForReceiptAsync(
        byte[] resourceId,
        string grantee
    );

    Task<TransactionReceipt> RevokeAccessRequestAndWaitForReceiptAsync(
        byte[] resourceId,
        string grantee
    );
}

// Batch calls (BatchCallSystemService)
public class BatchCallSystemService
{
    Task<TransactionReceipt> BatchCallRequestAndWaitForReceiptAsync(
        List<SystemCallData> systemCalls
    );
}

Usage Examples

Example 1: Setup World Service

using Nethereum.Web3;
using Nethereum.Mud.Contracts.World;

var web3 = new Web3("https://rpc.mud.game");
var worldAddress = "0xWorldContractAddress";

var worldService = new WorldService(web3, worldAddress);

Console.WriteLine($"Connected to World at {worldAddress}");

Example 2: Call a MUD System

using Nethereum.Mud;
using Nethereum.Mud.Contracts.World;
using Nethereum.Mud.EncodingDecoding;
using Nethereum.Contracts;

// Create resource ID for the system
var systemId = ResourceEncoder.EncodeSystem("Game", "MoveSystem");

// Encode function call (e.g., move(direction))
var moveFunction = new MoveFunction { Direction = 1 }; // Assuming generated function DTO
var callData = moveFunction.GetCallData(); // byte[]

// Call the system via World
var receipt = await worldService.CallRequestAndWaitForReceiptAsync(
    systemId,
    callData
);

Console.WriteLine($"System called successfully. Tx: {receipt.TransactionHash}");

Example 3: Query MUD Table

using Nethereum.Mud;
using Nethereum.Mud.Contracts.Store;

// Assuming generated PlayerTableService
var playerTableService = new PlayerTableService(web3, worldAddress);

// Query single record by key
var playerId = 42;
var playerRecord = await playerTableService.GetTableRecordAsync(playerId);

Console.WriteLine($"Player: {playerRecord.Values.Name}");
Console.WriteLine($"Level: {playerRecord.Values.Level}");
Console.WriteLine($"Health: {playerRecord.Values.Health}");

Example 4: Query Store Events

using Nethereum.Mud.Contracts.Core.StoreEvents;
using Nethereum.Mud.EncodingDecoding;

var storeEventsService = new StoreEventsLogProcessingService(web3, worldAddress);

// Get all SetRecord events
var setRecordEvents = await storeEventsService.GetAllSetRecord(
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

foreach (var log in setRecordEvents)
{
    var evt = log.Event;
    Console.WriteLine($"Record updated:");
    Console.WriteLine($"  TableId: {evt.TableId.ToHex()}");
    Console.WriteLine($"  Keys: {string.Join(", ", evt.KeyTuple.Select(k => k.ToHex()))}");
    Console.WriteLine($"  Block: {log.Log.BlockNumber.Value}");
}

// Get SetRecord events for a specific table
var playerTableId = ResourceEncoder.EncodeTable("Game", "Player");
var playerEvents = await storeEventsService.GetAllSetRecordForTable(
    playerTableId,
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

Console.WriteLine($"Found {playerEvents.Count} player table events");

Example 5: Process Store Events to Repository

using Nethereum.Mud.Contracts.Core.StoreEvents;
using Nethereum.Mud.TableRepository;

// Create table repository
var playerRepository = new InMemoryTableRepository();

// Setup event processing
var storeEventsService = new StoreEventsLogProcessingService(web3, worldAddress);
var progressRepository = new InMemoryBlockchainProgressRepository();

var processor = storeEventsService.CreateProcessor(
    playerRepository,
    progressRepository,
    log: null,
    numberOfBlocksPerRequest: 1000,
    retryWeight: 50,
    minimumNumberOfConfirmations: 12
);

// Start processing from block 0
await processor.ExecuteAsync(
    startAtBlockNumberIfNotProcessed: 0,
    cancellationToken: CancellationToken.None
);

Console.WriteLine("Store events processed to repository");

Example 6: Batch System Calls

using Nethereum.Mud.Contracts.World;
using Nethereum.Mud.Contracts.World.Systems.BatchCallSystem;
using Nethereum.Mud.EncodingDecoding;

// Prepare multiple system calls
var systemCalls = new List<SystemCallData>
{
    new SystemCallData
    {
        SystemId = ResourceEncoder.EncodeSystem("Game", "MoveSystem"),
        CallData = EncodeMoveCall(direction: 1)
    },
    new SystemCallData
    {
        SystemId = ResourceEncoder.EncodeSystem("Game", "AttackSystem"),
        CallData = EncodeAttackCall(targetId: 5)
    },
    new SystemCallData
    {
        SystemId = ResourceEncoder.EncodeSystem("Game", "CraftSystem"),
        CallData = EncodeCraftCall(itemId: 10, quantity: 1)
    }
};

// Execute all calls in one transaction via BatchCallSystemService
var batchCallService = new BatchCallSystemService(web3, worldAddress);
var receipt = await batchCallService.BatchCallRequestAndWaitForReceiptAsync(systemCalls);

Console.WriteLine($"Batch call successful. Gas used: {receipt.GasUsed.Value}");

Example 7: Grant and Revoke Access

using Nethereum.Mud;
using Nethereum.Mud.Contracts.World.Systems.AccessManagementSystem;
using Nethereum.Mud.EncodingDecoding;

// Create resource ID for a table
var tableId = ResourceEncoder.EncodeTable("Game", "Player");

// Use AccessManagementSystemService for access control
var accessService = new AccessManagementSystemService(web3, worldAddress);

// Grant access to an address
var granteeAddress = "0xGranteeAddress";
var grantReceipt = await accessService.GrantAccessRequestAndWaitForReceiptAsync(
    tableId,
    granteeAddress
);

Console.WriteLine($"Access granted to {granteeAddress}");

// Revoke access
var revokeReceipt = await accessService.RevokeAccessRequestAndWaitForReceiptAsync(
    tableId,
    granteeAddress
);

Console.WriteLine($"Access revoked from {granteeAddress}");

Example 8: Deploy MUD World

using Nethereum.Mud.Contracts.World.ContractDefinition;
using Nethereum.Web3.Accounts;

var account = new Account("0xPrivateKey", chainId: 1);
var web3 = new Web3(account, "https://rpc.mud.game");

// Deploy World contract
var deploymentMessage = new WorldDeployment();
var deploymentReceipt = await WorldService.DeployContractAndWaitForReceiptAsync(
    web3,
    deploymentMessage
);

var worldAddress = deploymentReceipt.ContractAddress;
Console.WriteLine($"World deployed at: {worldAddress}");

Example 9: Register Custom Table

using System.Collections.Generic;
using Nethereum.Mud;
using Nethereum.Mud.EncodingDecoding;

// Define table schema
var playerTableId = ResourceEncoder.EncodeTable("Game", "Player");
var schema = SchemaEncoder.GetSchemaEncoded<PlayerKey, PlayerValue>(
    playerTableId
);

// Register table via RegistrationSystemService
var registrationService = new RegistrationSystemService(web3, worldAddress);
var registerTableReceipt = await registrationService.RegisterTableRequestAndWaitForReceiptAsync(
    tableId: playerTableId,
    fieldLayout: schema.FieldLayout,
    keySchema: schema.KeySchema,
    valueSchema: schema.ValueSchema,
    keyNames: new List<string> { "playerId" },
    fieldNames: new List<string> { "name", "level", "health" }
);

Console.WriteLine("Table registered: Game:Player");

Example 10: Read Table Schema from Chain

using Nethereum.Mud.Contracts.Store.Tables;
using Nethereum.Mud.EncodingDecoding;

// TablesTableService queries the on-chain Tables table
var tablesService = new TablesTableService(web3, worldAddress);

// Get schema for a specific table
var playerTableId = ResourceEncoder.EncodeTable("Game", "Player");
var tableRecord = await tablesService.GetTableRecordAsync(playerTableId);

var schema = tableRecord.GetTableSchema();
Console.WriteLine($"Table: {schema.Name}");
Console.WriteLine($"Namespace: {schema.Namespace}");
Console.WriteLine($"Keys: {string.Join(", ", schema.SchemaKeys.Select(k => k.Name))}");
Console.WriteLine($"Values: {string.Join(", ", schema.SchemaValues.Select(v => v.Name))}");

Core Classes

WorldService

public class WorldService : ContractWeb3ServiceBase
{
    public WorldService(IWeb3 web3, string contractAddress);

    // System calls
    Task<TransactionReceipt> CallRequestAndWaitForReceiptAsync(
        byte[] systemId,
        byte[] callData
    );

    Task<TransactionReceipt> CallFromRequestAndWaitForReceiptAsync(
        string delegator,
        byte[] systemId,
        byte[] callData
    );
}

AccessManagementSystemService

public class AccessManagementSystemService
{
    Task<TransactionReceipt> GrantAccessRequestAndWaitForReceiptAsync(
        byte[] resourceId,
        string grantee
    );

    Task<TransactionReceipt> RevokeAccessRequestAndWaitForReceiptAsync(
        byte[] resourceId,
        string grantee
    );
}

BatchCallSystemService

public class BatchCallSystemService
{
    Task<TransactionReceipt> BatchCallRequestAndWaitForReceiptAsync(
        List<SystemCallData> systemCalls
    );
}

RegistrationSystemService

public class RegistrationSystemService
{
    Task<TransactionReceipt> RegisterTableRequestAndWaitForReceiptAsync(
        byte[] tableId,
        byte[] fieldLayout,
        byte[] keySchema,
        byte[] valueSchema,
        List<string> keyNames,
        List<string> fieldNames
    );
}

StoreEventsLogProcessingService

public class StoreEventsLogProcessingService
{
    public StoreEventsLogProcessingService(IWeb3 web3, string contractAddress);

    // Query all SetRecord events
    Task<List<EventLog<StoreSetRecordEventDTO>>> GetAllSetRecord(...);
    Task<List<EventLog<StoreSetRecordEventDTO>>> GetAllSetRecordForTable(byte[] tableId, ...);

    // Query all SpliceStaticData events
    Task<List<EventLog<StoreSpliceStaticDataEventDTO>>> GetAllSpliceStaticData(...);
    Task<List<EventLog<StoreSpliceStaticDataEventDTO>>> GetAllSpliceStaticDataForTable(byte[] tableId, ...);

    // Process all store changes (SetRecord, DeleteRecord, SpliceStaticData, SpliceDynamicData)
    Task ProcessAllStoreChangesAsync(ITableRepository tableRepository, ...);
    Task ProcessAllStoreChangesAsync(ITableRepository tableRepository, byte[] tableId, ...);
    Task ProcessAllStoreChangesAsync(ITableRepository tableRepository, string nameSpace, string tableName, ...);
}

Generated Table Service

Example of a generated table service:

Generated table services derive from TableService<TTableRecord, TKey, TValue>, inheriting its read/write methods and adding a typed convenience overload built from the table's key fields:

public partial class PlayerTableService
    : TableService<PlayerTableRecord, PlayerKey, PlayerValue>
{
    public PlayerTableService(IWeb3 web3, string contractAddress);

    // Generated convenience overload: builds the PlayerKey from the key fields
    Task<PlayerTableRecord> GetTableRecordAsync(
        BigInteger playerId,
        BlockParameter blockParameter = null
    );

    // --- Inherited from TableService base ---

    // Query a single record by its typed key
    // Task<PlayerTableRecord> GetTableRecordAsync(PlayerKey key, BlockParameter blockParameter = null);

    // Query multiple records by key in a single multicall
    // Task<List<PlayerTableRecord>> GetTableRecordsMulticallRpcAsync(List<PlayerKey> key, BlockParameter blockParameter = null);

    // Read all records previously indexed into a table repository
    // Task<IEnumerable<PlayerTableRecord>> GetTableRecordsAsync(ITableRepository tableRepository);

    // Set / delete records through the World
    // Task<TransactionReceipt> SetRecordRequestAndWaitForReceiptAsync(PlayerKey key, PlayerValue value);
    // Task<TransactionReceipt> DeleteRecordRequestAndWaitForReceiptAsync(PlayerKey key);
}

Store Event DTOs

[Event("Store_SetRecord")]
public class StoreSetRecordEventDTO : IEventDTO
{
    [Parameter("bytes32", "tableId", 1, true)]
    public byte[] TableId { get; set; }

    [Parameter("bytes32[]", "keyTuple", 2, false)]
    public List<byte[]> KeyTuple { get; set; }

    [Parameter("bytes", "staticData", 3, false)]
    public byte[] StaticData { get; set; }

    [Parameter("bytes32", "encodedLengths", 4, false)]
    public byte[] EncodedLengths { get; set; }

    [Parameter("bytes", "dynamicData", 5, false)]
    public byte[] DynamicData { get; set; }
}

[Event("Store_DeleteRecord")]
public class StoreDeleteRecordEventDTO : IEventDTO
{
    [Parameter("bytes32", "tableId", 1, true)]
    public byte[] TableId { get; set; }

    [Parameter("bytes32[]", "keyTuple", 2, false)]
    public List<byte[]> KeyTuple { get; set; }
}

Code Generation

Generate table and system services using .nethereum-gen.multisettings:

Configuration

{
  "paths": ["mud.config.ts"],
  "generatorConfigs": [
    {
      "baseNamespace": "MyGame.Tables",
      "basePath": "../MyGame/Tables",
      "generatorType": "MudTables"
    },
    {
      "baseNamespace": "MyGame.Systems",
      "basePath": "../MyGame/Systems",
      "generatorType": "MudExtendedService"
    }
  ]
}

Generated Output

MudTables generates:

• PlayerTableRecord.gen.cs - Table record with Keys and Values
• PlayerTableService.gen.cs - Service for querying the table

MudExtendedService generates:

• MoveSystemService.gen.cs - Service for calling system functions
• Function DTOs for all system methods

Running Generation

# Install Nethereum code generator
dotnet tool install -g Nethereum.Generator.Console

# Generate C# code
Nethereum.Generator.Console generate from-config -cfg .nethereum-gen.multisettings

# Or use VS Code extension
# https://github.com/juanfranblanco/vscode-solidity

Event Processing Patterns

Pattern 1: Query and Process Events

var storeEventsService = new StoreEventsLogProcessingService(web3, worldAddress);

// Query all SetRecord events
var events = await storeEventsService.GetAllSetRecord(
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

foreach (var eventLog in events)
{
    var evt = eventLog.Event;

    // Update local repository
    await UpdateRepositoryFromEvent(evt);

    // Notify UI
    await NotifyUIAsync(evt);
}

Pattern 2: Historical Event Processing

var storeEventsService = new StoreEventsLogProcessingService(web3, worldAddress);
var progressRepo = new InMemoryBlockchainProgressRepository();
var tableRepo = new InMemoryTableRepository();

var processor = storeEventsService.CreateProcessor(
    tableRepo,
    progressRepo,
    log: null,
    numberOfBlocksPerRequest: 1000,
    retryWeight: 50,
    minimumNumberOfConfirmations: 12
);

// Process all historical events
await processor.ExecuteAsync(
    startAtBlockNumberIfNotProcessed: 0,
    cancellationToken: CancellationToken.None
);

Pattern 3: Process All Store Changes to Repository

var storeEventsService = new StoreEventsLogProcessingService(web3, worldAddress);
var tableRepo = new InMemoryTableRepository();

// Process all store changes (SetRecord, DeleteRecord, SpliceStaticData, SpliceDynamicData)
await storeEventsService.ProcessAllStoreChangesAsync(
    tableRepo,
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

// Or process changes for a specific table only
var playerTableId = ResourceEncoder.EncodeTable("Game", "Player");
await storeEventsService.ProcessAllStoreChangesAsync(
    tableRepo,
    playerTableId,
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

Advanced Topics

Custom Event Handlers

public class CustomEventHandler
{
    public async Task HandleSetRecord(StoreSetRecordEventDTO evt)
    {
        // Custom logic for SetRecord
        var tableId = evt.TableId.ToHex();

        if (tableId == playerTableId)
        {
            await HandlePlayerUpdate(evt);
        }
        else if (tableId == inventoryTableId)
        {
            await HandleInventoryUpdate(evt);
        }
    }
}

Filtering Events by Table

var playerTableId = ResourceEncoder.EncodeTable("Game", "Player");

// Use GetAllSetRecordForTable to query events for a specific table
var playerEvents = await storeEventsService.GetAllSetRecordForTable(
    playerTableId,
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

foreach (var eventLog in playerEvents)
{
    // Only receives events for Player table
    var playerEvent = eventLog.Event;
    await HandlePlayerUpdate(playerEvent);
}

Handling Splice Events

// Query static data splice events
var spliceStaticEvents = await storeEventsService.GetAllSpliceStaticData(
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

foreach (var eventLog in spliceStaticEvents)
{
    var evt = eventLog.Event;
    Console.WriteLine($"Static data spliced:");
    Console.WriteLine($"  TableId: {evt.TableId.ToHex()}");
    Console.WriteLine($"  Start: {evt.Start}");
    Console.WriteLine($"  New data length: {evt.Data.Length}");
}

// Or use ProcessAllStoreChangesAsync to handle all event types
// (SetRecord, DeleteRecord, SpliceStaticData, SpliceDynamicData)
// and apply them to a table repository automatically
await storeEventsService.ProcessAllStoreChangesAsync(
    tableRepository,
    fromBlockNumber: 0,
    toBlockNumber: null,
    cancellationToken: CancellationToken.None
);

Production Patterns

1. Decentralized Game Client

// Initialize World connection
var worldService = new WorldService(web3, worldAddress);

// Load initial state by indexing Store events into a repository
var tableRepository = new InMemoryTableRepository();
var storeEventsService = new StoreEventsLogProcessingService(web3, worldAddress);
await storeEventsService.ProcessAllStoreChangesAsync(tableRepository);

var playerTable = new PlayerTableService(web3, worldAddress);
var players = await playerTable.GetTableRecordsAsync(tableRepository);

// Subscribe to updates
var subscription = await SubscribeToStoreEvents(worldAddress);

// User action: Move player
var moveSystemId = ResourceEncoder.EncodeSystem("Game", "MoveSystem");
await worldService.CallRequestAndWaitForReceiptAsync(
    moveSystemId,
    EncodeMoveCall(direction: 1)
);

2. MUD Indexer

The Nethereum.Mud.Repositories.Postgres package ships a Postgres-backed indexer built on Entity Framework Core. Point MudPostgresStoreRecordsProcessingService at the World and RPC endpoint; it resumes from the last processed block on restart.

using Microsoft.EntityFrameworkCore;
using Nethereum.Mud.Repositories.Postgres;

// Configure the EF Core DbContext for Postgres
var options = new DbContextOptionsBuilder<MudPostgresStoreRecordsDbContext>()
    .UseNpgsql(connectionString)
    .UseLowerCaseNamingConvention()
    .Options;

using var context = new MudPostgresStoreRecordsDbContext(options);
await context.Database.MigrateAsync();

// Index all Store events (SetRecord, DeleteRecord, Splice) into Postgres
var processingService = new MudPostgresStoreRecordsProcessingService(context, logger)
{
    Address = worldAddress,
    RpcUrl = rpcUrl,
    StartAtBlockNumberIfNotProcessed = 0,
    NumberOfBlocksToProcessPerRequest = 1000,
    RetryWeight = 50,
    MinimumNumberOfConfirmations = 12
};

await processingService.ExecuteAsync(cancellationToken);

For a hosted service that reads its configuration (connection string, World address, RPC URL) from IConfiguration, register the shipped background indexer instead:

services.AddMudPostgresProcessing(configuration, connectionString);

3. Multi-World Aggregator

// Query data from multiple MUD Worlds
var world1Service = new WorldService(web3, world1Address);
var world2Service = new WorldService(web3, world2Address);

var player1Table = new PlayerTableService(web3, world1Address);
var player2Table = new PlayerTableService(web3, world2Address);

// Aggregate player data from both worlds (indexed into repositories first)
var repo1 = new InMemoryTableRepository();
var repo2 = new InMemoryTableRepository();
await new StoreEventsLogProcessingService(web3, world1Address).ProcessAllStoreChangesAsync(repo1);
await new StoreEventsLogProcessingService(web3, world2Address).ProcessAllStoreChangesAsync(repo2);

var players1 = await player1Table.GetTableRecordsAsync(repo1);
var players2 = await player2Table.GetTableRecordsAsync(repo2);

var allPlayers = players1.Concat(players2).ToList();

Related Packages

Dependencies

• Nethereum.Mud - Core MUD types and table records
• Nethereum.Web3 - Ethereum client

Used By

• Nethereum.Mud.Repositories.EntityFramework - EF Core event processing
• Nethereum.Mud.Repositories.Postgres - PostgreSQL event processing

Related

• Nethereum.Contracts - Contract interaction base

Additional Resources

• MUD Documentation
• MUD World Contract
• MUD Store Protocol
• Nethereum MUD Console Tests

Support

• Nethereum Discord
• GitHub Issues