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
| 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. |