Store
Reference
StoreCore (internal)

StoreCore

Git Source (opens in a new tab)

This library includes implementations for all IStore methods and events related to the store actions.

Functions

initialize

Initialize the store address in StoreSwitch.

Consumers must call this function in their constructor. StoreSwitch uses the storeAddress to decide where to write data to. If StoreSwitch is called in the context of a Store contract (storeAddress == address(this)), StoreSwitch uses internal methods to write data instead of external calls.

function initialize() internal;

registerInternalTables

Register Store protocol's internal tables in the store.

Consumers must call this function in their constructor before setting any table data to allow indexers to decode table events.

function registerInternalTables() internal;

getFieldLayout

SCHEMA

Get the field layout for the given table ID.

function getFieldLayout(ResourceId tableId) internal view returns (FieldLayout);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table for which to get the field layout.

Returns

NameTypeDescription
<none>FieldLayoutThe field layout for the given table ID.

getKeySchema

Get the key schema for the given table ID.

Reverts if the table ID is not registered.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table for which to get the key schema.

Returns

NameTypeDescription
keySchemaSchemaThe key schema for the given table ID.

getValueSchema

Get the value schema for the given table ID.

Reverts if the table ID is not registered.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table for which to get the value schema.

Returns

NameTypeDescription
valueSchemaSchemaThe value schema for the given table ID.

registerTable

Usage Sample

Register a new table with the given configuration.

*This method reverts if

  • The table ID is not of type RESOURCE_TABLE or RESOURCE_OFFCHAIN_TABLE.
  • The field layout is invalid.
  • The key schema is invalid.
  • The value schema is invalid.
  • The number of key names does not match the number of key schema types.
  • The number of field names does not match the number of field layout fields.*
function registerTable(
  ResourceId tableId,
  FieldLayout fieldLayout,
  Schema keySchema,
  Schema valueSchema,
  string[] memory keyNames,
  string[] memory fieldNames
) internal;

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to register.
fieldLayoutFieldLayoutThe field layout of the table.
keySchemaSchemaThe key schema of the table.
valueSchemaSchemaThe value schema of the table.
keyNamesstring[]The names of the keys in the table.
fieldNamesstring[]The names of the fields in the table.

registerStoreHook

Usage Sample

REGISTER HOOKS

Register hooks to be called when a record or field is set or deleted.

This method reverts for all resource IDs other than tables. Hooks are not supported for offchain tables.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to register the hook for.
hookAddressIStoreHookThe address of the hook contract to register.
enabledHooksBitmapuint8The bitmap of enabled hooks.

unregisterStoreHook

Unregister a hook from the given table ID.

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) internal;

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to unregister the hook from.
hookAddressIStoreHookThe address of the hook to unregister.

setRecord

Set a full record for the given table ID and key tuple.

Calling this method emits a Store_SetRecord event. This method internally calls another overload of setRecord by fetching the field layout for the given table ID. If the field layout is available to the caller, it is recommended to use the other overload to avoid an additional storage read.

function setRecord(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  bytes memory staticData,
  EncodedLengths encodedLengths,
  bytes memory dynamicData
) internal;

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to set the record for.
keyTuplebytes32[]An array representing the composite key for the record.
staticDatabytesThe static data of the record.
encodedLengthsEncodedLengthsThe encoded lengths of the dynamic data of the record.
dynamicDatabytesThe dynamic data of the record.

setRecord

Set a full data record for the given table ID, key tuple, and field layout.

For onchain tables, the method emits a Store_SetRecord event, updates the data in storage, calls onBeforeSetRecord hooks before actually modifying the state, and calls onAfterSetRecord hooks after modifying the state. For offchain tables, the method returns early after emitting the event without calling hooks or modifying the state.

function setRecord(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  bytes memory staticData,
  EncodedLengths encodedLengths,
  bytes memory dynamicData,
  FieldLayout fieldLayout
) internal;

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to set the record for.
keyTuplebytes32[]An array representing the composite key for the record.
staticDatabytesThe static data of the record.
encodedLengthsEncodedLengthsThe encoded lengths of the dynamic data of the record.
dynamicDatabytesThe dynamic data of the record.
fieldLayoutFieldLayoutThe field layout for the record.

spliceStaticData

Splice the static data for the given table ID and key tuple.

This method emits a Store_SpliceStaticData event, updates the data in storage, and calls onBeforeSpliceStaticData and onAfterSpliceStaticData hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to splice the static data for.
keyTuplebytes32[]An array representing the composite key for the record.
startuint48The start position in bytes for the splice operation.
databytesThe data to write to the static data of the record at the start byte.

spliceDynamicData

Splice the dynamic data for the given table ID, key tuple, and dynamic field index.

This method emits a Store_SpliceDynamicData event, updates the data in storage, and calls onBeforeSpliceDynamicData and onAfterSpliceDynamicData hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to splice the dynamic data for.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field to splice. (Dynamic field index = field index - number of static fields)
startWithinFielduint40The start position within the field for the splice operation.
deleteCountuint40The number of bytes to delete in the splice operation.
databytesThe data to insert into the dynamic data of the record at the start byte.

setField

Set data for a field at the given index in a table with the given tableId, key tuple, and value field layout.

This method internally calls another overload of setField by fetching the field layout for the given table ID. If the field layout is available to the caller, it is recommended to use the other overload to avoid an additional storage read. This function emits a Store_SpliceStaticData or Store_SpliceDynamicData event and calls the corresponding hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to set the field for.
keyTuplebytes32[]An array representing the key for the record.
fieldIndexuint8The index of the field to set.
databytesThe data to set for the field.

setField

Set data for a field at the given index in a table with the given tableId, key tuple, and value field layout.

This method internally calls to setStaticField or setDynamicField based on the field index and layout. Calling setStaticField or setDynamicField directly is recommended if the caller is aware of the field layout. This function emits a Store_SpliceStaticData or Store_SpliceDynamicData event, updates the data in storage, and calls the corresponding hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to set the field for.
keyTuplebytes32[]An array representing the composite key for the record.
fieldIndexuint8The index of the field to set.
databytesThe data to set for the field.
fieldLayoutFieldLayoutThe field layout for the record.

setStaticField

Set a static field for the given table ID, key tuple, field index, and field layout.

This method emits a Store_SpliceStaticData event, updates the data in storage and calls the onBeforeSpliceStaticData and onAfterSpliceStaticData hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to set the static field for.
keyTuplebytes32[]An array representing the key for the record.
fieldIndexuint8The index of the field to set.
databytesThe data to set for the static field.
fieldLayoutFieldLayoutThe field layout for the record.

setDynamicField

Set a dynamic field for the given table ID, key tuple, and dynamic field index.

This method emits a Store_SpliceDynamicData event, updates the data in storage and calls the onBeforeSpliceDynamicaData and onAfterSpliceDynamicData hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to set the dynamic field for.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field to set. (Dynamic field index = field index - number of static fields).
databytesThe data to set for the dynamic field.

deleteRecord

Delete a record for the given table ID and key tuple.

This method internally calls another overload of deleteRecord by fetching the field layout for the given table ID. This method deletes static data and sets the dynamic data length to 0, but does not actually modify the dynamic data. It emits a Store_DeleteRecord event and emits the onBeforeDeleteRecord and onAfterDeleteRecord hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to delete the record from.
keyTuplebytes32[]An array representing the composite key for the record.

deleteRecord

Delete a record for the given table ID and key tuple.

This method deletes static data and sets the dynamic data length to 0, but does not actually modify the dynamic data. It emits a Store_DeleteRecord event and emits the onBeforeDeleteRecord and onAfterDeleteRecord hooks. For offchain tables, it returns early after emitting the event.

function deleteRecord(ResourceId tableId, bytes32[] memory keyTuple, FieldLayout fieldLayout) internal;

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to delete the record from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldLayoutFieldLayoutThe field layout for the record.

pushToDynamicField

Push data to a field at the dynamic field index in a table with the given table ID and key tuple.

This method emits a Store_SpliceDynamicData event, updates the data in storage and calls the onBeforeSpliceDynamicData and onAfterSpliceDynamicData hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to push data to the dynamic field.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field to push data to.
dataToPushbytesThe data to push to the dynamic field.

popFromDynamicField

Pop data from a field at the dynamic field index in a table with the given table ID and key tuple.

This method emits a Store_SpliceDynamicData event, updates the data in storage and calls the onBeforeSpliceDynamicData and onAfterSpliceDynamicData hooks. For offchain tables, it returns early after emitting the event.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to pop data from the dynamic field.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field to pop data from.
byteLengthToPopuint256The byte length to pop from the dynamic field.

getRecord

Get the full record (all fields, static and dynamic data) for the given table ID and key tuple.

This function internally calls another overload of getRecord, loading the field layout from storage. If the field layout is available to the caller, it is recommended to use the other overload to avoid an additional storage read.

function getRecord(
  ResourceId tableId,
  bytes32[] memory keyTuple
) internal view returns (bytes memory staticData, EncodedLengths encodedLengths, bytes memory dynamicData);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the record from.
keyTuplebytes32[]An array representing the composite key for the record.

Returns

NameTypeDescription
staticDatabytesThe static data of the record.
encodedLengthsEncodedLengthsThe encoded lengths of the dynamic data of the record.
dynamicDatabytesThe dynamic data of the record.

getRecord

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

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the record from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldLayoutFieldLayoutThe field layout for the record.

Returns

NameTypeDescription
staticDatabytesThe static data of the record.
encodedLengthsEncodedLengthsThe encoded lengths of the dynamic data of the record.
dynamicDatabytesThe dynamic data of the record.

getField

Get a single field from the given table ID and key tuple.

This function internally calls another overload of getField, loading the field layout from storage.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the field from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldIndexuint8The index of the field to get.

Returns

NameTypeDescription
<none>bytesThe data of the field.

getField

Get a single field from the given table ID and key tuple, with the given field layout.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the field from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldIndexuint8The index of the field to get.
fieldLayoutFieldLayoutThe field layout for the record.

Returns

NameTypeDescription
<none>bytesThe data of the field.

getStaticField

Get a single static field from the given table ID and key tuple, with the given value field layout.

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[] memory keyTuple,
  uint8 fieldIndex,
  FieldLayout fieldLayout
) internal view returns (bytes32);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the static field from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldIndexuint8The index of the field to get.
fieldLayoutFieldLayoutThe field layout for the record.

Returns

NameTypeDescription
<none>bytes32The data of the static field.

getDynamicField

Get a single dynamic field from the given table ID and key tuple.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the dynamic field from.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field to get, relative to the start of the dynamic fields. (Dynamic field index = field index - number of static fields)

Returns

NameTypeDescription
<none>bytesThe data of the dynamic field.

getFieldLength

Get the byte length of a single field from the given table ID and key tuple.

This function internally calls another overload of getFieldLength, loading the field layout from storage. If the field layout is available to the caller, it is recommended to use the other overload to avoid an additional storage read.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the field length from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldIndexuint8The index of the field to get the length for.

Returns

NameTypeDescription
<none>uint256The byte length of the field.

getFieldLength

Get the byte length of a single field from the given table ID and key tuple.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the field length from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldIndexuint8The index of the field to get the length for.
fieldLayoutFieldLayoutThe field layout for the record.

Returns

NameTypeDescription
<none>uint256The byte length of the field.

getDynamicFieldLength

Get the byte length of a single dynamic field from the given table ID and key tuple.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the dynamic field length from.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field to get the length for, relative to the start of the dynamic fields. (Dynamic field index = field index - number of static fields)

Returns

NameTypeDescription
<none>uint256The byte length of the dynamic field.

getDynamicFieldSlice

Get a byte slice (including start, excluding end) of a single dynamic field from the given table ID and key tuple.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the dynamic field slice from.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field to get the slice from, relative to the start of the dynamic fields. (Dynamic field index = field index - number of static fields)
startuint256The start index within the dynamic field for the slice operation (inclusive).
enduint256The end index within the dynamic field for the slice operation (exclusive).

Returns

NameTypeDescription
<none>bytesThe byte slice of the dynamic field.

StoreCoreInternal

Git Source (opens in a new tab)

This library contains internal functions used by StoreCore. They are not intended to be used directly by consumers of StoreCore.

State Variables

SLOT

bytes32 internal constant SLOT = keccak256("mud.store");

DYNAMIC_DATA_SLOT

bytes32 internal constant DYNAMIC_DATA_SLOT = keccak256("mud.store.dynamicData");

DYNAMIC_DATA_LENGTH_SLOT

bytes32 internal constant DYNAMIC_DATA_LENGTH_SLOT = keccak256("mud.store.dynamicDataLength");

Functions

_spliceDynamicData

Splice dynamic data in the store.

This function checks various conditions to ensure the operation is valid. It emits a Store_SpliceDynamicData event, calls onBeforeSpliceDynamicData hooks before actually modifying the storage, and calls onAfterSpliceDynamicData hooks after modifying the storage. It reverts with Store_InvalidResourceType if the table ID is not a table. (Splicing dynamic data is not supported for offchain tables, as it requires reading the previous encoded lengths from storage.) It reverts with Store_InvalidSplice if the splice total length of the field is changed but the splice is not at the end of the field. It reverts with Store_IndexOutOfBounds if the start index is larger than the previous length of the field.

function _spliceDynamicData(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 dynamicFieldIndex,
  uint40 startWithinField,
  uint40 deleteCount,
  bytes memory data,
  EncodedLengths previousEncodedLengths
) internal;

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to splice dynamic data.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The 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)
startWithinFielduint40The start index within the field for the splice operation.
deleteCountuint40The number of bytes to delete in the splice operation.
databytesThe data to insert into the dynamic data of the record at the start byte.
previousEncodedLengthsEncodedLengthsThe previous encoded lengths of the dynamic data of the record.

_getStaticData

Get full static data for the given table ID and key tuple, with the given length in bytes.

function _getStaticData(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint256 length
) internal view returns (bytes memory);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the static data from.
keyTuplebytes32[]An array representing the composite key for the record.
lengthuint256The length of the static data to retrieve.

Returns

NameTypeDescription
<none>bytesThe full static data of the specified length.

_getStaticFieldBytes

Get a single static field from the given table ID and key tuple, with the given value field layout.

function _getStaticFieldBytes(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 fieldIndex,
  FieldLayout fieldLayout
) internal view returns (bytes memory);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to get the static field from.
keyTuplebytes32[]An array representing the composite key for the record.
fieldIndexuint8The index of the field to get.
fieldLayoutFieldLayoutThe field layout for the record.

Returns

NameTypeDescription
<none>bytesThe static field data as dynamic bytes in the size of the field.

_getStaticDataLocation

Compute the storage location based on table ID and key tuple.

function _getStaticDataLocation(ResourceId tableId, bytes32[] memory keyTuple) internal pure returns (uint256);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]An array representing the composite key for the record.

Returns

NameTypeDescription
<none>uint256The computed storage location based on table ID and key tuple.

_getStaticDataLocation

Compute the storage location based on table ID and a single key.

function _getStaticDataLocation(ResourceId tableId, bytes32 key) internal pure returns (uint256);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keybytes32The single key for the record.

Returns

NameTypeDescription
<none>uint256The computed storage location based on table ID and key.

_getStaticDataOffset

Get storage offset for the given value field layout and index.

function _getStaticDataOffset(FieldLayout fieldLayout, uint8 fieldIndex) internal pure returns (uint256);

Parameters

NameTypeDescription
fieldLayoutFieldLayoutThe field layout for the record.
fieldIndexuint8The index of the field to get the offset for.

Returns

NameTypeDescription
<none>uint256The storage offset for the specified field layout and index.

_getDynamicDataLocation

Compute the storage location based on table ID, key tuple, and dynamic field index.

function _getDynamicDataLocation(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  uint8 dynamicFieldIndex
) internal pure returns (uint256);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]An array representing the composite key for the record.
dynamicFieldIndexuint8The index of the dynamic field, relative to the start of the dynamic fields. (Dynamic field index = field index - number of static fields)

Returns

NameTypeDescription
<none>uint256The computed storage location based on table ID, key tuple, and dynamic field index.

_getDynamicDataLengthLocation

Compute the storage location for the length of the dynamic data based on table ID and key tuple.

function _getDynamicDataLengthLocation(ResourceId tableId, bytes32[] memory keyTuple) internal pure returns (uint256);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]An array representing the composite key for the record.

Returns

NameTypeDescription
<none>uint256The computed storage location for the length of the dynamic data based on table ID and key tuple.

_loadEncodedDynamicDataLength

Load the encoded dynamic data length from storage for the given table ID and key tuple.

function _loadEncodedDynamicDataLength(
  ResourceId tableId,
  bytes32[] memory keyTuple
) internal view returns (EncodedLengths);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]An array representing the composite key for the record.

Returns

NameTypeDescription
<none>EncodedLengthsThe loaded encoded dynamic data length from storage for the given table ID and key tuple.

StoreKernel

Git Source (opens in a new tab)

Inherits: IStoreKernel, StoreRead

This contract integrates the storage functionalities except registration and provides an interface for data storage.

This abstract contract initializes StoreCore, implements storeVersion, and read methods.

Functions

constructor

Constructs the StoreKernel contract and initializes the StoreCore.

Emits a HelloStore event upon creation.

constructor();

storeVersion

Retrieves the protocol version of the Store.

function storeVersion() public pure returns (bytes32);

Returns

NameTypeDescription
<none>bytes32The protocol version of the Store.

Store

Git Source (opens in a new tab)

Inherits: IStore, StoreKernel

This contract integrates the core storage functionalities and provides an interface for data storage.

This abstract contract initializes StoreCore, implements storeVersion, and read methods, but not write methods.

StoreRead

Git Source (opens in a new tab)

Inherits: IStoreRead

A contract that provides read operations for storage tables using StoreCore.

Functions

getFieldLayout

Fetches the field layout for a given table.

function getFieldLayout(ResourceId tableId) public view virtual returns (FieldLayout fieldLayout);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table for which to retrieve the field layout.

Returns

NameTypeDescription
fieldLayoutFieldLayoutThe layout of fields in the specified table.

getValueSchema

Retrieves the value schema for a given table.

function getValueSchema(ResourceId tableId) public view virtual returns (Schema valueSchema);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.

Returns

NameTypeDescription
valueSchemaSchemaThe schema for values in the specified table.

getKeySchema

Retrieves the key schema for a given table.

function getKeySchema(ResourceId tableId) public view virtual returns (Schema keySchema);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.

Returns

NameTypeDescription
keySchemaSchemaThe schema for keys in the specified table.

getRecord

Fetches a record from a specified table using a provided key tuple.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key to fetch the record.

Returns

NameTypeDescription
staticDatabytesThe static data of the record.
encodedLengthsEncodedLengthsEncoded lengths of dynamic data.
dynamicDatabytesThe dynamic data of the record.

getRecord

Fetches a record from a specified table using a provided key tuple and field layout.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key to fetch the record.
fieldLayoutFieldLayoutThe layout of fields to retrieve.

Returns

NameTypeDescription
staticDatabytesThe static data of the record.
encodedLengthsEncodedLengthsEncoded lengths of dynamic data.
dynamicDatabytesThe dynamic data of the record.

getField

Retrieves data for a specified field in a record.

This overload loads the FieldLayout from storage. If the table's FieldLayout is known to the caller, it should be passed in to the other overload to avoid the storage read.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key to fetch the field.
fieldIndexuint8Index of the field to retrieve.

Returns

NameTypeDescription
databytesThe data of the specified field.

getField

Retrieves data for a specified field in a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key to fetch the field.
fieldIndexuint8Index of the field to retrieve.
fieldLayoutFieldLayoutThe layout of fields for the retrieval.

Returns

NameTypeDescription
databytesThe data of the specified field.

getStaticField

Retrieves data for a specific static (fixed length) field in a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key to fetch the static field.
fieldIndexuint8Index of the static field to retrieve.
fieldLayoutFieldLayoutThe layout of fields for the retrieval.

Returns

NameTypeDescription
databytes32The static data of the specified field.

getDynamicField

Retrieves data for a specific dynamic (variable length) field in a record.

function getDynamicField(
  ResourceId tableId,
  bytes32[] calldata keyTuple,
  uint8 dynamicFieldIndex
) public view virtual returns (bytes memory data);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key to fetch the dynamic field.
dynamicFieldIndexuint8Index of the dynamic field to retrieve.

Returns

NameTypeDescription
databytesThe dynamic data of the specified field.

getFieldLength

Calculates the length of a specified field in a record.

This overload loads the FieldLayout from storage. If the table's FieldLayout is known to the caller, it should be passed in to the other overload to avoid the storage read.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key.
fieldIndexuint8Index of the field to measure.

Returns

NameTypeDescription
<none>uint256The length of the specified field.

getFieldLength

Calculates the length of a specified field in a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key.
fieldIndexuint8Index of the field to measure.
fieldLayoutFieldLayoutThe layout of fields for measurement.

Returns

NameTypeDescription
<none>uint256The length of the specified field.

getDynamicFieldLength

Calculates the length of a specified dynamic (variable length) field in a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key.
dynamicFieldIndexuint8Index of the dynamic field to measure.

Returns

NameTypeDescription
<none>uint256The length of the specified dynamic field.

getDynamicFieldSlice

Retrieves a slice of a dynamic (variable length) field.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table.
keyTuplebytes32[]The tuple used as a key to fetch the dynamic field slice.
dynamicFieldIndexuint8Index of the dynamic field to slice.
startuint256The starting position of the slice.
enduint256The ending position of the slice.

Returns

NameTypeDescription
<none>bytesThe sliced data from the specified dynamic field.

StoreSwitch

Usage SampleGit Source (opens in a new tab)

This library serves as an interface switch to interact with the store, either by directing calls to itself or to a designated external store.

The primary purpose is to abstract the storage details, such that the calling function doesn't need to know if it's interacting with its own storage or with an external contract's storage.

State Variables

STORAGE_SLOT

Internal constant representing the storage slot used by the library.

bytes32 private constant STORAGE_SLOT = keccak256("mud.store.storage.StoreSwitch");

Functions

_layout

Gets the storage layout.

function _layout() private pure returns (StorageSlotLayout storage layout);

Returns

NameTypeDescription
layoutStorageSlotLayoutThe current storage layout.

getStoreAddress

Fetch the store address to be used for data operations. If _storeAddress is zero, it means that it's uninitialized and therefore it's the default (msg.sender).

function getStoreAddress() internal view returns (address);

Returns

NameTypeDescription
<none>addressAddress of the store, or msg.sender if uninitialized.

setStoreAddress

Usage Sample

Set the store address for subsequent operations.

If it stays uninitialized, StoreSwitch falls back to calling store methods on msg.sender.

function setStoreAddress(address _storeAddress) internal;

Parameters

NameTypeDescription
_storeAddressaddressThe address of the external store contract.

registerStoreHook

Register a store hook for a particular table.

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

Parameters

NameTypeDescription
tableIdResourceIdUnique identifier of the table.
hookAddressIStoreHookAddress of the hook contract.
enabledHooksBitmapuint8Bitmap representing the hooks which this contract overrides.

unregisterStoreHook

Unregister a previously registered store hook.

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) internal;

Parameters

NameTypeDescription
tableIdResourceIdUnique identifier of the table.
hookAddressIStoreHookAddress of the hook contract to be unregistered.

getFieldLayout

Fetches the field layout for a specified table.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table for which to retrieve the field layout.

Returns

NameTypeDescription
fieldLayoutFieldLayoutThe layout of the fields in the specified table.

getValueSchema

Retrieves the value schema for a specified table.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table for which to retrieve the value schema.

Returns

NameTypeDescription
valueSchemaSchemaThe schema for values in the specified table.

getKeySchema

Retrieves the key schema for a specified table.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table for which to retrieve the key schema.

Returns

NameTypeDescription
keySchemaSchemaThe schema for keys in the specified table.

registerTable

Registers a table with specified configurations.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to register.
fieldLayoutFieldLayoutThe layout of the fields for the table.
keySchemaSchemaThe schema for keys in the table.
valueSchemaSchemaThe schema for values in the table.
keyNamesstring[]Names of keys in the table.
fieldNamesstring[]Names of fields in the table.

setRecord

Sets a record in the store.

function setRecord(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  bytes memory staticData,
  EncodedLengths encodedLengths,
  bytes memory dynamicData
) internal;

Parameters

NameTypeDescription
tableIdResourceIdThe table's ID.
keyTuplebytes32[]Array of key values.
staticDatabytesFixed-length fields data.
encodedLengthsEncodedLengthsEncoded lengths for dynamic data.
dynamicDatabytesDynamic-length fields data.

spliceStaticData

Splices the static (fixed length) data for a given table ID and key tuple, starting at a specific point.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the resource table.
keyTuplebytes32[]An array of bytes32 keys identifying the data record.
startuint48The position to begin splicing.
databytesThe data to splice into the record.

spliceDynamicData

Splices the dynamic data for a given table ID, key tuple, and dynamic field index.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the resource table.
keyTuplebytes32[]An array of bytes32 keys identifying the data record.
dynamicFieldIndexuint8The index of the dynamic field to splice.
startWithinFielduint40The position within the dynamic field to start splicing.
deleteCountuint40The number of bytes to delete starting from the splice point.
databytesThe data to splice into the dynamic field.

setField

Sets the data for a specific field in a record identified by table ID and key tuple.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the resource table.
keyTuplebytes32[]An array of bytes32 keys identifying the data record.
fieldIndexuint8The index of the field to set.
databytesThe data to set for the field.

setField

Sets the data for a specific field in a record, considering a specific field layout.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the resource table.
keyTuplebytes32[]An array of bytes32 keys identifying the data record.
fieldIndexuint8The index of the field to set.
databytesThe data to set for the field.
fieldLayoutFieldLayoutThe layout structure of the field.

setStaticField

Sets the data for a specific static (fixed length) field in a record, considering a specific field layout.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the resource table.
keyTuplebytes32[]An array of bytes32 keys identifying the data record.
fieldIndexuint8The index of the field to set.
databytesThe data to set for the field.
fieldLayoutFieldLayoutThe layout structure of the field.

setDynamicField

Sets the value of a specific dynamic (variable-length) field in a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
dynamicFieldIndexuint8The index of the dynamic field to set.
databytesThe data to set for the field.

pushToDynamicField

Appends data to a specific dynamic (variable length) field of a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
dynamicFieldIndexuint8The index of the dynamic field.
dataToPushbytesThe data to append to the field.

popFromDynamicField

Removes data from the end of a specific dynamic (variable length) field of a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
dynamicFieldIndexuint8The index of the dynamic field.
byteLengthToPopuint256The number of bytes to remove from the end of the field.

deleteRecord

Deletes a record from a table.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.

getRecord

Retrieves a record from a table.

function getRecord(
  ResourceId tableId,
  bytes32[] memory keyTuple
) internal view returns (bytes memory, EncodedLengths, bytes memory);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.

Returns

NameTypeDescription
<none>bytesstaticData The static data of the record.
<none>EncodedLengthsencodedLengths Encoded lengths of dynamic data.
<none>bytesdynamicData The dynamic data of the record.

getRecord

Retrieves a record from a table with a specific layout.

function getRecord(
  ResourceId tableId,
  bytes32[] memory keyTuple,
  FieldLayout fieldLayout
) internal view returns (bytes memory, EncodedLengths, bytes memory);

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
fieldLayoutFieldLayoutThe layout of the fields in the record.

Returns

NameTypeDescription
<none>bytesstaticData The static data of the record.
<none>EncodedLengthsencodedLengths Encoded lengths of dynamic data.
<none>bytesdynamicData The dynamic data of the record.

getField

Retrieves a specific field from a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
fieldIndexuint8The index of the field to retrieve.

Returns

NameTypeDescription
<none>bytesReturns the data of the specified field.

getField

Retrieves a specific field from a record with a given layout.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
fieldIndexuint8The index of the field to retrieve.
fieldLayoutFieldLayoutThe layout of the field being retrieved.

Returns

NameTypeDescription
<none>bytesReturns the data of the specified field.

getStaticField

Retrieves a specific static (fixed length) field from a record with a given layout.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
fieldIndexuint8The index of the static field to retrieve.
fieldLayoutFieldLayoutThe layout of the static field being retrieved.

Returns

NameTypeDescription
<none>bytes32Returns the data of the specified static field.

getDynamicField

Retrieves a specific dynamic (variable length) field from a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
dynamicFieldIndexuint8The index of the dynamic field to retrieve.

Returns

NameTypeDescription
<none>bytesReturns the data of the specified dynamic field.

getFieldLength

Retrieves the length of a specific field in a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
fieldIndexuint8The index of the field whose length is to be retrieved.

Returns

NameTypeDescription
<none>uint256Returns the length of the specified field.

getFieldLength

Retrieves the length of a specific field in a record with a given layout.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
fieldIndexuint8The index of the field whose length is to be retrieved.
fieldLayoutFieldLayoutThe layout of the field whose length is to be retrieved.

Returns

NameTypeDescription
<none>uint256Returns the length of the specified field.

getDynamicFieldLength

Retrieves the length of a specific dynamic (variable length) field in a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
dynamicFieldIndexuint8The index of the dynamic field whose length is to be retrieved.

Returns

NameTypeDescription
<none>uint256Returns the length of the specified dynamic field.

getDynamicFieldSlice

Retrieves a slice of a dynamic (variable length) field from a record.

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

Parameters

NameTypeDescription
tableIdResourceIdThe ID of the table to which the record belongs.
keyTuplebytes32[]An array representing the key for the record.
dynamicFieldIndexuint8The index of the dynamic field from which to get the slice.
startuint256The starting index of the slice.
enduint256The ending index of the slice.

Returns

NameTypeDescription
<none>bytesReturns the sliced data from the specified dynamic field.

Structs

StorageSlotLayout

Represents the layout of the storage slot (currently just the address)

struct StorageSlotLayout {
  address storeAddress;
}