Store – MUD

IStore

Inherits: IStoreKernel, IStoreRegistration

IStoreEvents

Events

HelloStore

Emitted when the Store is created.

event HelloStore(bytes32 indexed storeVersion);

Parameters

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

Store_SetRecord

Emitted when a new record is set in the store.

event Store_SetRecord(
  ResourceId indexed tableId,
  bytes32[] keyTuple,
  bytes staticData,
  EncodedLengths 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`	`EncodedLengths`	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,
  uint8 dynamicFieldIndex,
  uint48 start,
  uint40 deleteCount,
  EncodedLengths 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.
`dynamicFieldIndex`	`uint8`	The index of the dynamic field to splice data, relative to the start of the dynamic fields. (Dynamic field index = field index - number of static fields)
`start`	`uint48`	The start position in bytes for the splice operation.
`deleteCount`	`uint40`	The number of bytes to delete in the splice operation.
`encodedLengths`	`EncodedLengths`	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)

This interface includes errors for Store.

We bundle these errors in an interface (instead of at the file-level or in their corresponding library) so they can be inherited by IStore. This ensures that all possible errors are included in the IStore ABI for proper decoding in the frontend.

Errors

Store_TableAlreadyExists

Error raised if the provided table already exists.

error Store_TableAlreadyExists(ResourceId tableId, string tableIdString);

Parameters

Name	Type	Description
`tableId`	`ResourceId`	The ID of the table.
`tableIdString`	`string`	The stringified ID of the table (for easier debugging if cleartext tableIds are used).

Store_TableNotFound

Error raised if the provided table cannot be found.

error Store_TableNotFound(ResourceId tableId, string tableIdString);

Parameters

Name	Type	Description
`tableId`	`ResourceId`	The ID of the table.
`tableIdString`	`string`	The stringified ID of the table (for easier debugging if cleartext tableIds are used).

Store_InvalidResourceType

Error raised if the provided resource ID cannot be found.

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

Parameters

Name	Type	Description
`expected`	`bytes2`	The expected resource type.
`resourceId`	`ResourceId`	The resource ID.
`resourceIdString`	`string`	The stringified resource ID (for easier debugging).

Store_InvalidBounds

Error raised if the provided slice bounds are invalid.

error Store_InvalidBounds(uint256 start, uint256 end);

Parameters

Name	Type	Description
`start`	`uint256`	The start index within the dynamic field for the slice operation (inclusive).
`end`	`uint256`	The end index within the dynamic field for the slice operation (exclusive).

Store_IndexOutOfBounds

Error raised if the provided index is out of bounds.

Raised if the start index is larger than the previous length of the field.

error Store_IndexOutOfBounds(uint256 length, uint256 accessedIndex);

Parameters

Name	Type	Description
`length`	`uint256`	FIXME
`accessedIndex`	`uint256`	FIXME

Store_InvalidStaticDataLength

Error raised if the provided static data length is invalid.

error Store_InvalidStaticDataLength(uint256 expected, uint256 received);

Parameters

Name	Type	Description
`expected`	`uint256`	The expected length.
`received`	`uint256`	The provided length.

Store_InvalidKeyNamesLength

Error raised if the provided key names length is invalid.

error Store_InvalidKeyNamesLength(uint256 expected, uint256 received);

Parameters

Name	Type	Description
`expected`	`uint256`	The expected length.
`received`	`uint256`	The provided length.

Store_InvalidFieldNamesLength

Error raised if the provided field names length is invalid.

error Store_InvalidFieldNamesLength(uint256 expected, uint256 received);

Parameters

Name	Type	Description
`expected`	`uint256`	The expected length.
`received`	`uint256`	The provided length.

Store_InvalidValueSchemaLength

Error raised if the provided value schema length is invalid.

error Store_InvalidValueSchemaLength(uint256 expected, uint256 received);

Parameters

Name	Type	Description
`expected`	`uint256`	The expected length.
`received`	`uint256`	The provided length.

Store_InvalidValueSchemaStaticLength

Error raised if the provided schema static length is invalid.

error Store_InvalidValueSchemaStaticLength(uint256 expected, uint256 received);

Parameters

Name	Type	Description
`expected`	`uint256`	The expected length.
`received`	`uint256`	The provided length.

Store_InvalidValueSchemaDynamicLength

Error raised if the provided schema dynamic length is invalid.

error Store_InvalidValueSchemaDynamicLength(uint256 expected, uint256 received);

Parameters

Name	Type	Description
`expected`	`uint256`	The expected length.
`received`	`uint256`	The provided length.

Store_InvalidSplice

Error raised if the provided splice is invalid.

Raised if the splice total length of the field is changed but the splice is not at the end of the field.

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

Parameters

Name	Type	Description
`startWithinField`	`uint40`	The start index within the field for the splice operation.
`deleteCount`	`uint40`	The number of bytes to delete in the splice operation.
`fieldLength`	`uint40`	The field length for the splice operation.

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, EncodedLengths 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, EncodedLengths 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,
  EncodedLengths 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)

This 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

Usage Sample

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

registerStoreHook

Usage Sample

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

unregisterStoreHook

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) external;

IStoreKernel

Git Source (opens in a new tab)

Inherits: IStoreRead, IStoreWrite, IStoreErrors, IFieldLayoutErrors, IEncodedLengthsErrors, ISchemaErrors, ISliceErrors

IStoreKernel includes the error interfaces for each library that it uses.

Functions

storeVersion

Returns the protocol version of the Store contract.

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

Returns

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

StoreCore (internal)StoreHook