Skip to content

Latest commit

 

History

History
848 lines (623 loc) · 36.9 KB

store-core.mdx

File metadata and controls

848 lines (623 loc) · 36.9 KB
Raw

StoreCore

Git Source

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

Name Type Description
tableId ResourceId The ID of the table for which to get the field layout.

Returns

Name Type Description
<none> FieldLayout The 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

Name Type Description
tableId ResourceId The ID of the table for which to get the key schema.

Returns

Name Type Description
keySchema Schema The 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

Name Type Description
tableId ResourceId The ID of the table for which to get the value schema.

Returns

Name Type Description
valueSchema Schema The value schema for the given table ID.

registerTable

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

Name Type Description
tableId ResourceId The ID of the table to register.
fieldLayout FieldLayout The field layout of the table.
keySchema Schema The key schema of the table.
valueSchema Schema The value schema of the table.
keyNames string[] The names of the keys in the table.
fieldNames string[] The names of the fields in the table.

registerStoreHook

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

Name Type Description
tableId ResourceId The ID of the table to register the hook for.
hookAddress IStoreHook The address of the hook contract to register.
enabledHooksBitmap uint8 The bitmap of enabled hooks.

unregisterStoreHook

Unregister a hook from the given table ID.

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) internal;

Parameters

Name Type Description
tableId ResourceId The ID of the table to unregister the hook from.
hookAddress IStoreHook The address of the hook to unregister.

setRecord

SET DATA

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,
  PackedCounter encodedLengths,
  bytes memory dynamicData
) internal;

Parameters

Name Type Description
tableId ResourceId The ID of the table to set the record for.
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.

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,
  PackedCounter encodedLengths,
  bytes memory dynamicData,
  FieldLayout fieldLayout
) internal;

Parameters

Name Type Description
tableId ResourceId The ID of the table to set the record for.
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.
fieldLayout FieldLayout The 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

Name Type Description
tableId ResourceId The ID of the table to splice the static data for.
keyTuple bytes32[] An array representing the composite 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.

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

Name Type Description
tableId ResourceId The ID of the table to splice the dynamic data for.
keyTuple bytes32[] An array representing the composite key for the record.
dynamicFieldIndex uint8 The index of the dynamic field to splice. (Dynamic field index = field index - number of static fields)
startWithinField uint40 The start position within the field for the splice operation.
deleteCount uint40 The number of bytes to delete in the splice operation.
data bytes The 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

Name Type Description
tableId ResourceId The ID of the table to set the field for.
keyTuple bytes32[] An array representing the key for the record.
fieldIndex uint8 The index of the field to set.
data bytes The 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

Name Type Description
tableId ResourceId The ID of the table to set the field for.
keyTuple bytes32[] An array representing the composite key for the record.
fieldIndex uint8 The index of the field to set.
data bytes The data to set for the field.
fieldLayout FieldLayout The 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

Name Type Description
tableId ResourceId The ID of the table to set the static field for.
keyTuple bytes32[] An array representing the key for the record.
fieldIndex uint8 The index of the field to set.
data bytes The data to set for the static field.
fieldLayout FieldLayout The 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

Name Type Description
tableId ResourceId The ID of the table to set the dynamic field for.
keyTuple bytes32[] An array representing the composite key for the record.
dynamicFieldIndex uint8 The index of the dynamic field to set. (Dynamic field index = field index - number of static fields).
data bytes The 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

Name Type Description
tableId ResourceId The ID of the table to delete the record from.
keyTuple bytes32[] 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

Name Type Description
tableId ResourceId The ID of the table to delete the record from.
keyTuple bytes32[] An array representing the composite key for the record.
fieldLayout FieldLayout The 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

Name Type Description
tableId ResourceId The ID of the table to push data to the dynamic field.
keyTuple bytes32[] An array representing the composite key for the record.
dynamicFieldIndex uint8 The index of the dynamic field to push data to.
dataToPush bytes The 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

Name Type Description
tableId ResourceId The ID of the table to pop data from the dynamic field.
keyTuple bytes32[] An array representing the composite key for the record.
dynamicFieldIndex uint8 The index of the dynamic field to pop data from.
byteLengthToPop uint256 The byte length to pop from the dynamic field.

getRecord

GET DATA

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, PackedCounter encodedLengths, bytes memory dynamicData);

Parameters

Name Type Description
tableId ResourceId The ID of the table to get the record from.
keyTuple bytes32[] An array representing the composite key for the record.

Returns

Name Type Description
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.

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, PackedCounter encodedLengths, bytes memory dynamicData);

Parameters

Name Type Description
tableId ResourceId The ID of the table to get the record from.
keyTuple bytes32[] An array representing the composite key for the record.
fieldLayout FieldLayout The field layout for the record.

Returns

Name Type Description
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.

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

Name Type Description
tableId ResourceId The ID of the table to get the field from.
keyTuple bytes32[] An array representing the composite key for the record.
fieldIndex uint8 The index of the field to get.

Returns

Name Type Description
<none> bytes The 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

Name Type Description
tableId ResourceId The ID of the table to get the field from.
keyTuple bytes32[] An array representing the composite key for the record.
fieldIndex uint8 The index of the field to get.
fieldLayout FieldLayout The field layout for the record.

Returns

Name Type Description
<none> bytes The 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

Name Type Description
tableId ResourceId The ID of the table to get the static field from.
keyTuple bytes32[] An array representing the composite key for the record.
fieldIndex uint8 The index of the field to get.
fieldLayout FieldLayout The field layout for the record.

Returns

Name Type Description
<none> bytes32 The 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

Name Type Description
tableId ResourceId The ID of the table to get the dynamic field from.
keyTuple bytes32[] An array representing the composite key for the record.
dynamicFieldIndex uint8 The 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

Name Type Description
<none> bytes The 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

Name Type Description
tableId ResourceId The ID of the table to get the field length from.
keyTuple bytes32[] An array representing the composite key for the record.
fieldIndex uint8 The index of the field to get the length for.

Returns

Name Type Description
<none> uint256 The 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

Name Type Description
tableId ResourceId The ID of the table to get the field length from.
keyTuple bytes32[] An array representing the composite key for the record.
fieldIndex uint8 The index of the field to get the length for.
fieldLayout FieldLayout The field layout for the record.

Returns

Name Type Description
<none> uint256 The 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

Name Type Description
tableId ResourceId The ID of the table to get the dynamic field length from.
keyTuple bytes32[] An array representing the composite key for the record.
dynamicFieldIndex uint8 The 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

Name Type Description
<none> uint256 The 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

Name Type Description
tableId ResourceId The ID of the table to get the dynamic field slice from.
keyTuple bytes32[] An array representing the composite key for the record.
dynamicFieldIndex uint8 The 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)
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).

Returns

Name Type Description
<none> bytes The byte slice of the dynamic field.

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,
    uint8 dynamicFieldIndex,
    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.
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 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.