I’ve noticed our naming has become inconsistent over time and I want to formalize some naming so we can create consistency across the entire stack (Solidity, TS, etc.). Once formalized, we can update naming everywhere (including protocol events, etc.).

Store

type KeyName = string;
type Key = Record<KeyName, StaticAbiPrimitiveType>;
type KeyTuple = StaticAbiPrimitiveType[];
type KeySchema = Record<KeyName, StaticAbiType>;

type FieldName = string;
type FieldValue = SchemaAbiPrimitiveType;
type Value = Record<FieldName, FieldValue>;
type ValueSchema = Record<FieldName, SchemaAbiType>;

type TableId = Hex; // bytes32

// Record is a key/value pair
type TableRecord = {
  key: Key;
  value: Value;
}

type Table = {
  tableId: TableId;
  keySchema: KeySchema;
  valueSchema: ValueSchema;
  records: TableRecord[];
}

library Table {
  setRecord(key1, key2, TableData value);
  setRecord(key1, key2, fieldValue1, fieldValue2);
  setFieldName(key1, key2, fieldValue);
	deleteRecord(key1, key2);
}

World

• Namespace - a group of access-controlled resources, e.g. tables and systems.
• System - contains write logic/behavior, generally access controlled and called via world
• Hook - extends behavior of one or more methods, registered on the world
• Module - a collection of systems and hooks to extend the default behavior of a world, store, or table. Effectively an “installer”.

MUD framework

Store and World are moving away from namespace/name as a built-in concept and instead delegating that responsibility to an access control module/hook via a bytes32 resource ID. The default access control module, provided by the MUD framework (along with MUD config, codegen, sync) will use a namespace and tableName (packed into the bytes32) to represent tables in config, on-chain, and in the indexer.

import { Table as StoreTable } from 'store';

type Namespace = string; // bytes14
type TableName = string; // bytes16

type Table = StoreTable & {
  namespace: Namespace;
  tableName: TableName;
}

export default mudConfig({
  // top-level tables default to the root namespace
  tables: {
    SomeTable: {
      keySchema: {
        x: "uint32",
        y: "uint32",
      },
      valueSchema: {
        player: "address",
      },
    },
  },
});

bytes32 tableId = ResourceSelector.from(namespace, tableName);

Similarly, systems use a combination of namespace and systemName for their resource ID and for access control.

Resources

• Resources have a bytes32 identifier. This was previously called “resource selector”, but is now renamed to “resource ID”.
• There are different types of resources. When talking about the umbrella concept of a resource identifier, resourceId / “resource ID” should be used. When talking about a specific resource, a more specific term should be used:
  • Systems: systemId
  • Tables: tableId
  • Delegation control: delegationId

Namespaces

• In places where humans interact with namespaced resources, these resources should be named/represented as {namespace}__{resourceName} (note the double underscore).