Skip to content

Latest commit

 

History

History
639 lines (453 loc) · 19.6 KB

store.mdx

File metadata and controls

639 lines (453 loc) · 19.6 KB
Raw

IStore

Git Source

Inherits: IStoreData, IStoreRegistration, IStoreErrors, IFieldLayoutErrors, IPackedCounterErrors, ISchemaErrors, ISliceErrors

IStore implements the error interfaces for each library that it uses.

IStoreEvents

Git Source

Events

HelloStore

Emitted when the Store is created.

event HelloStore(bytes32 indexed storeVersion);

Parameters

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

Store_SetRecord

Emitted when a new record is set in the store.

event Store_SetRecord(
  ResourceId indexed tableId,
  bytes32[] keyTuple,
  bytes staticData,
  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.

IStoreErrors

Git Source

This interface includes errors for Store.

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

Errors

Store_TableAlreadyExists

Error raised if the provided table already exists.

error Store_TableAlreadyExists(ResourceId tableId, string tableIdString);

Parameters

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

Store_TableNotFound

Error raised if the provided table cannot be found.

error Store_TableNotFound(ResourceId tableId, string tableIdString);

Parameters

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

Store_InvalidResourceType

Error raised if the provided resource ID cannot be found.

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

Parameters

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

Store_InvalidBounds

Error raised if the provided slice bounds are invalid.

error Store_InvalidBounds(uint256 start, uint256 end);

Parameters

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

Store_IndexOutOfBounds

Error raised if the provided index is out of bounds.

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

error Store_IndexOutOfBounds(uint256 length, uint256 accessedIndex);

Parameters

Name Type Description
length uint256 FIXME
accessedIndex uint256 FIXME

Store_InvalidStaticDataLength

Error raised if the provided static data length is invalid.

error Store_InvalidStaticDataLength(uint256 expected, uint256 received);

Parameters

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

Store_InvalidKeyNamesLength

Error raised if the provided key names length is invalid.

error Store_InvalidKeyNamesLength(uint256 expected, uint256 received);

Parameters

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

Store_InvalidFieldNamesLength

Error raised if the provided field names length is invalid.

error Store_InvalidFieldNamesLength(uint256 expected, uint256 received);

Parameters

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

Store_InvalidValueSchemaLength

Error raised if the provided value schema length is invalid.

error Store_InvalidValueSchemaLength(uint256 expected, uint256 received);

Parameters

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

Store_InvalidValueSchemaStaticLength

Error raised if the provided schema static length is invalid.

error Store_InvalidValueSchemaStaticLength(uint256 expected, uint256 received);

Parameters

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

Store_InvalidValueSchemaDynamicLength

Error raised if the provided schema dynamic length is invalid.

error Store_InvalidValueSchemaDynamicLength(uint256 expected, uint256 received);

Parameters

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

Store_InvalidSplice

Error raised if the provided splice is invalid.

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

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

Parameters

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

IStoreData

Git Source

Inherits: IStoreRead, IStoreWrite

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

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

Functions

storeVersion

Returns the version of the Store contract.

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

Returns

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

IStoreRead

Git Source

Functions

getFieldLayout

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

getValueSchema

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

getKeySchema

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

getRecord

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

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

getRecord

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

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

getField

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

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

getField

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

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

getStaticField

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

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

getDynamicField

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

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

getFieldLength

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

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

getFieldLength

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

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

getDynamicFieldLength

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

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

getDynamicFieldSlice

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

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

IStoreWrite

Git Source

Inherits: IStoreEvents

Functions

setRecord

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

spliceStaticData

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

spliceDynamicData

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

setField

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

setField

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

setStaticField

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

setDynamicField

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

pushToDynamicField

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

popFromDynamicField

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

deleteRecord

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

IStoreRegistration

Git Source

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

Functions

registerTable

Usage Sample

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

registerStoreHook

Usage Sample

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

unregisterStoreHook

function unregisterStoreHook(ResourceId tableId, IStoreHook hookAddress) external;