From 48b88b864ef8b21c91d4f894a5dadd0efcbd31c4 Mon Sep 17 00:00:00 2001 From: alvrs Date: Tue, 10 Oct 2023 17:55:47 +0200 Subject: [PATCH 1/2] docs: add store/introduction --- next-docs/pages/store/introduction.mdx | 48 ++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/next-docs/pages/store/introduction.mdx b/next-docs/pages/store/introduction.mdx index e10b99d013..5b86ff4c47 100644 --- a/next-docs/pages/store/introduction.mdx +++ b/next-docs/pages/store/introduction.mdx @@ -1 +1,49 @@ # Introduction + +`Store` is an alternative to Solidity's storage engine. +It enforces a data model that can be mapped directly to a relational database, +enables [automatic indexing](../services/indexer) by emitting events on each storage operation, +and [packs data more tightly](./encoding) than Solidity's storage engine. + +## Data model + +Each piece of data in `Store` is stored as a _record_ in a _table_. +You can think of tables in two ways, either as a relational database, +or as a key-value store. + +- Each table is identified by a unique `ResourceId tableId`. +- Each record in a table is identified by a unique `bytes32[] keyTuple`. + You can think of the key tuple as a composite key in a relational database, + or as a nested mapping in a key-value store. +- Each table has a `ValueSchema` that defines the types of data stored in the table. + You can think of the value schema as the column types in a table in a relational database, + or the type of structs stored in a key-value store. + +## Reading and writing data + +The [`StoreCore`](./reference) library implements low level methods for reading and writing data +in a `Store` contract and the [`IStore`](./reference) interface exposes some of these methods +to external callers. + +Due to the lack of generics in Solidity, the only way to allow functions act on +data of different types is to cast the data to raw "untyped" `bytes`. +To improve the developer experience, `Store` automatically [generates +a library for each table](./table-libraries) which acts as a type wrapper. +These libraries provide getter and setter functions with strong types +for the table's keys and values, encode them using the [Store encoding](./encoding) +before passing them to the Store, and decode them before passing them back to the user. + +## Schema definition at runtime + +Unlike Solidity's storage engine, +which requires the storage types to be known at compile time, +`Store` allows new tables with new schemas to be registered after the `Store` contract has been deployed. +This allows advanced use-cases like the [`World` protocol](../world/introduction). + +## Automatic indexing + +`Store` automatically emits events on every write operation, +including when a new table is registered in the `Store` at runtime. +These events allow [automatic indexers](../services/indexer) to replicate the onchain state of each +table in each `Store` contract in a relational database for offchain use, +without the need for custom integrations. From 88eaac55a6fd43514da8d07f71f37766b086bdc0 Mon Sep 17 00:00:00 2001 From: alvrs Date: Tue, 10 Oct 2023 18:25:38 +0200 Subject: [PATCH 2/2] polish --- next-docs/pages/store/introduction.mdx | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/next-docs/pages/store/introduction.mdx b/next-docs/pages/store/introduction.mdx index 5b86ff4c47..4475ea2fe5 100644 --- a/next-docs/pages/store/introduction.mdx +++ b/next-docs/pages/store/introduction.mdx @@ -4,6 +4,8 @@ It enforces a data model that can be mapped directly to a relational database, enables [automatic indexing](../services/indexer) by emitting events on each storage operation, and [packs data more tightly](./encoding) than Solidity's storage engine. +It also allows external contract storage to be read onchain without being limited +by existing `view` functions and [without a new opcode](https://eips.ethereum.org/EIPS/eip-2330). ## Data model @@ -33,6 +35,21 @@ These libraries provide getter and setter functions with strong types for the table's keys and values, encode them using the [Store encoding](./encoding) before passing them to the Store, and decode them before passing them back to the user. +```solidity +// Example: reading and writing data via table libraries + +// The Position table library turns the typed +// address parameter into a bytes32[] keyTuple, +// and decodes the return value to (uint32, uint32). +(uint32 x, uint32 y) = Position.get(msg.sender); + +// The Position table library turns the typed +// address parameter into a bytes32[] keyTyple, +// and encodes the (uint32,uint32) tuple into +// a tightly packed bytes blob. +Position.set(msg.sender, x, y); +``` + ## Schema definition at runtime Unlike Solidity's storage engine,