Store – MUD

IStore

Inherits: IStoreData, IStoreRegistration, IStoreErrors

IStoreEvents

Events

Store_SetRecord

Emitted when a new record is set in the store.

event Store_SetRecord(
    ResourceId indexed tableId, bytes32[] keyTuple, bytes staticData, PackedCounter encodedLengths, bytes dynamicData
);

Parameters

Name	Type	Description
`tableId`	`ResourceId`	The ID of the table where the record is set.
`keyTuple`	`bytes32[]`	An array representing the composite key for the record.
`staticData`	`bytes`	The static data of the record.
`encodedLengths`	`PackedCounter`	The encoded lengths of the dynamic data of the record.
`dynamicData`	`bytes`	The dynamic data of the record.

Store_SpliceStaticData

Emitted when static data in the store is spliced.

In static data, data is always overwritten starting at the start position, so the total length of the data remains the same and no data is shifted.

event Store_SpliceStaticData(ResourceId indexed tableId, bytes32[] keyTuple, uint48 start, bytes data);

Parameters

Name	Type	Description
`tableId`	`ResourceId`	The ID of the table where the data is spliced.
`keyTuple`	`bytes32[]`	An array representing the key for the record.
`start`	`uint48`	The start position in bytes for the splice operation.
`data`	`bytes`	The data to write to the static data of the record at the start byte.

Store_SpliceDynamicData

Emitted when dynamic data in the store is spliced.

event Store_SpliceDynamicData(
    ResourceId indexed tableId,
    bytes32[] keyTuple,
    uint48 start,
    uint40 deleteCount,
    PackedCounter encodedLengths,
    bytes data
);

Parameters

Name	Type	Description
`tableId`	`ResourceId`	The ID of the table where the data is spliced.
`keyTuple`	`bytes32[]`	An array representing the composite key for the record.
`start`	`uint48`	The start position in bytes for the splice operation.
`deleteCount`	`uint40`	The number of bytes to delete in the splice operation.
`encodedLengths`	`PackedCounter`	The encoded lengths of the dynamic data of the record.
`data`	`bytes`	The data to insert into the dynamic data of the record at the start byte.

Store_DeleteRecord

Emitted when a record is deleted from the store.

event Store_DeleteRecord(ResourceId indexed tableId, bytes32[] keyTuple);

Parameters

Name	Type	Description
`tableId`	`ResourceId`	The ID of the table where the record is deleted.
`keyTuple`	`bytes32[]`	An array representing the composite key for the record.

IStoreErrors

Git Source (opens in a new tab)

Errors

Store_TableAlreadyExists

error Store_TableAlreadyExists(ResourceId tableId, string tableIdString);

Store_TableNotFound

error Store_TableNotFound(ResourceId tableId, string tableIdString);

Store_InvalidResourceType

error Store_InvalidResourceType(bytes2 expected, ResourceId resourceId, string resourceIdString);

Store_InvalidDynamicDataLength

error Store_InvalidDynamicDataLength(uint256 expected, uint256 received);

Store_IndexOutOfBounds

error Store_IndexOutOfBounds(uint256 length, uint256 accessedIndex);

Store_InvalidKeyNamesLength

error Store_InvalidKeyNamesLength(uint256 expected, uint256 received);

Store_InvalidFieldNamesLength

error Store_InvalidFieldNamesLength(uint256 expected, uint256 received);

Store_InvalidValueSchemaLength

error Store_InvalidValueSchemaLength(uint256 expected, uint256 received);

Store_InvalidSplice

error Store_InvalidSplice(uint40 startWithinField, uint40 deleteCount, uint40 fieldLength);

IStoreData

Git Source (opens in a new tab)

Inherits: IStoreRead, IStoreWrite

The IStoreData interface includes methods for reading and writing table values.

These methods are frequently invoked during runtime, so it is essential to prioritize optimizing their gas cost.

Functions

storeVersion

Returns the version of the Store contract.

function storeVersion() external view returns (bytes32 version);

Returns

Name	Type	Description
`version`	`bytes32`	The version of the Store contract.

Events

HelloStore

Emitted when the store is initialized.

event HelloStore(bytes32 indexed storeVersion);

Parameters

Name	Type	Description
`storeVersion`	`bytes32`	The version of the Store contract.

IStoreRead

Git Source (opens in a new tab)

Functions

getFieldLayout

function getFieldLayout(ResourceId tableId) external view returns (FieldLayout fieldLayout);

getValueSchema

function getValueSchema(ResourceId tableId) external view returns (Schema valueSchema);

getKeySchema

function getKeySchema(ResourceId tableId) external view returns (Schema keySchema);

getRecord

Get full record (all fields, static and dynamic data) for the given tableId and key tuple, loading the field layout from storage

function getRecord(
  ResourceId tableId,
  bytes32[] calldata keyTuple
) external view returns (bytes memory staticData, PackedCounter encodedLengths, bytes memory dynamicData);

getRecord

Get full record (all fields, static and dynamic data) for the given tableId and key tuple, with the given field layout

function getRecord(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  FieldLayout fieldLayout
) external view returns (bytes memory staticData, PackedCounter encodedLengths, bytes memory dynamicData);

getField

Get a single field from the given tableId and key tuple, loading the field layout from storage

function getField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 fieldIndex
) external view returns (bytes memory data);

getField

Get a single field from the given tableId and key tuple, with the given field layout

function getField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 fieldIndex,
  FieldLayout fieldLayout
) external view returns (bytes memory data);

getStaticField

Get a single static field from the given tableId and key tuple, with the given value field layout. Note: the field value is left-aligned in the returned bytes32, the rest of the word is not zeroed out. Consumers are expected to truncate the returned value as needed.

function getStaticField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 fieldIndex,
  FieldLayout fieldLayout
) external view returns (bytes32);

getDynamicField

Get a single dynamic field from the given tableId and key tuple at the given dynamic field index. (Dynamic field index = field index - number of static fields)

function getDynamicField(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 dynamicFieldIndex
) external view returns (bytes memory);

getFieldLength

Get the byte length of a single field from the given tableId and key tuple, loading the field layout from storage

function getFieldLength(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 fieldIndex
) external view returns (uint256);

getFieldLength

Get the byte length of a single field from the given tableId and key tuple, with the given value field layout

function getFieldLength(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 fieldIndex,
  FieldLayout fieldLayout
) external view returns (uint256);

getDynamicFieldLength

Get the byte length of a single dynamic field from the given tableId and key tuple

function getDynamicFieldLength(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 dynamicFieldIndex
) external view returns (uint256);

getDynamicFieldSlice

Get a byte slice (including start, excluding end) of a single dynamic field from the given tableId and key tuple, with the given value field layout. The slice is unchecked and will return invalid data if start:end overflow.

function getDynamicFieldSlice(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 dynamicFieldIndex,
  uint256 start,
  uint256 end
) external view returns (bytes memory data);

IStoreWrite

Git Source (opens in a new tab)

Inherits: IStoreEvents

Functions

setRecord

function setRecord(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  bytes calldata staticData,
  PackedCounter encodedLengths,
  bytes calldata dynamicData
) external;

spliceStaticData

function spliceStaticData(ResourceId tableId, bytes32[] calldata keyTuple, uint48 start, bytes calldata data) external;

spliceDynamicData

function spliceDynamicData(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 dynamicFieldIndex,
  uint40 startWithinField,
  uint40 deleteCount,
  bytes calldata data
) external;

setField

function setField(ResourceId tableId, bytes32[] calldata keyTuple, uint8 fieldIndex, bytes calldata data) external;

setField

function setField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 fieldIndex,
  bytes calldata data,
  FieldLayout fieldLayout
) external;

setStaticField

function setStaticField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 fieldIndex,
  bytes calldata data,
  FieldLayout fieldLayout
) external;

setDynamicField

function setDynamicField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 dynamicFieldIndex,
  bytes calldata data
) external;

pushToDynamicField

function pushToDynamicField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 dynamicFieldIndex,
  bytes calldata dataToPush
) external;

popFromDynamicField

function popFromDynamicField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 dynamicFieldIndex,
  uint256 byteLengthToPop
) external;

deleteRecord

function deleteRecord(ResourceId tableId, bytes32[] memory keyTuple) external;

IStoreRegistration

Git Source (opens in a new tab)

The IStoreRegistration interface includes methods for managing table field layouts, metadata, and hooks, which are usually called once in the setup phase of an application, making them less performance critical than the methods.

Functions

registerTable

function registerTable(
  ResourceId tableId,
  FieldLayout fieldLayout,
  Schema keySchema,
  Schema valueSchema,
  string[] calldata keyNames,
  string[] calldata fieldNames
) external;

registerStoreHook

function registerStoreHook(ResourceId tableId, IStoreHook hookAddress, uint8 enabledHooksBitmap) external;

unregisterStoreHook

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) external;

StoreCore (internal)StoreHook