Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add ERC: Store, Table-Based Introspectable Storage #711

Open
wants to merge 8 commits into
base: master
Choose a base branch
from

Conversation

alvrs
Copy link

@alvrs alvrs commented Nov 8, 2024

This standard introduces a flexible on-chain storage pattern that organizes data into structured tables with schemas, similar to a traditional database. This approach allows new tables to be added at runtime without impacting existing contracts, thereby simplifying upgrades and extensions. By providing a unified interface for data access, the standard enables any contract or off-chain service to read stored data without the need for custom getter functions. Additionally, by standardizing event emissions for state changes it enables automatic, schema-aware indexing.

@eip-review-bot
Copy link
Collaborator

eip-review-bot commented Nov 8, 2024

File ERCS/erc-7813.md

Requires 1 more reviewers from @g11tech, @SamWilsn, @xinbenlv

@github-actions github-actions bot added the w-ci label Nov 8, 2024
@alvrs alvrs marked this pull request as ready for review November 8, 2024 16:53
ERCS/erc-xxxx.md Outdated Show resolved Hide resolved
ERCS/erc-xxxx.md Outdated Show resolved Hide resolved
ERCS/erc-xxxx.md Outdated Show resolved Hide resolved
ERCS/erc-xxxx.md Outdated
@@ -0,0 +1,499 @@
---
eip: <to be assigned>
title: Store, Table-Based Introspectable Storage
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
title: Store, Table-Based Introspectable Storage
title: Table-Based Introspectable Storage

Maybe simplify the title

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We would like to keep the name for now. Thanks for the feedback!

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For context - we feel it's important to keep the term "Store" in the title since it's the name of the pattern, ie all events are prefixed with Store

@github-actions github-actions bot removed the w-ci label Nov 18, 2024
Copy link

The commit d60529d (as a parent of 571b06e) contains errors.
Please inspect the Run Summary for details.

@github-actions github-actions bot added the w-ci label Nov 18, 2024
@github-actions github-actions bot removed the w-ci label Nov 27, 2024
@alvrs
Copy link
Author

alvrs commented Dec 4, 2024

@abcoathup please let us know if there are any other requested changes before we can get this merged as draft!


## Abstract

This standard introduces a flexible on-chain storage pattern that organizes data into structured tables with schemas, similar to a traditional database. This approach allows new tables to be added at runtime without impacting existing contracts, thereby simplifying upgrades and extensions. By providing a unified interface for data access, the standard enables any contract or off-chain service to read stored data without the need for custom getter functions. Additionally, by standardizing event emissions for state changes it enables automatic, schema-aware indexing.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your abstract is missing some technical meat. After reading this section, your audience should have a high level (but still technical) overview of how your proposal accomplishes its goals.


A piece of data stored in a **Table**, addressed by one or more keys.

#### ResourceId
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If these headings are literals from your code (and it looks like they might be), you should enclose them in backticks (`). That goes for any code snippets in the text as well.


#### Store_SetRecord

Setting a Record means overwriting all of its fields. This operation can be performed wether the record has been set before or not (the standard does not enforce existence checks).
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Setting a Record means overwriting all of its fields. This operation can be performed wether the record has been set before or not (the standard does not enforce existence checks).
Setting a Record means overwriting all of its fields. This operation can be performed whether the record has been set before or not (the standard does not enforce existence checks).


Setting a Record means overwriting all of its fields. This operation can be performed wether the record has been set before or not (the standard does not enforce existence checks).

The `Store_SetRecord` event **MUST** be emitted to signal that the full data of a record has been overwritten.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `Store_SetRecord` event **MUST** be emitted to signal that the full data of a record has been overwritten.
The `Store_SetRecord` event **MUST** be emitted whenever the full data of a record has been overwritten.

Is this more clear?


Splicing the static data of a Record consists in overwriting bytes of the packed encoded static fields. The total length of static data does not change as it is determined by the table’s value schema.

The `Store_SpliceStaticData` event MUST be emitted to signal that the static data of the Record has been spliced.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `Store_SpliceStaticData` event MUST be emitted to signal that the static data of the Record has been spliced.
The `Store_SpliceStaticData` event MUST be emitted whenever the static data of the Record has been spliced.


Splicing the dynamic data of a Record involves modifying the packed encoded representation of its dynamic fields by removing, replacing, and/or inserting new bytes in place.

The `Store_SpliceDynamicData` event MUST be emitted to signal that the dynamic data of the Record has been spliced.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `Store_SpliceDynamicData` event MUST be emitted to signal that the dynamic data of the Record has been spliced.
The `Store_SpliceDynamicData` event MUST be emitted whenever the dynamic data of the Record has been spliced.


#### Store_DeleteRecord

The `Store_DeleteRecord` event MUST be emitted to signal that the Record has been deleted from the Table.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `Store_DeleteRecord` event MUST be emitted to signal that the Record has been deleted from the Table.
The `Store_DeleteRecord` event MUST be emitted whenever the Record has been deleted from the Table.

| tableId | ResourceId | The ID of the table where the record is deleted |
| keyTuple | bytes32[] | An array representing the composite key for the record |

#### Example
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should probably be moved to your Reference Implementation section. You can link to it from here though.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants