From 90724f4694c4f334a1b0ac572458e728983b5bc0 Mon Sep 17 00:00:00 2001 From: "Alisher A. Khassanov" Date: Fri, 29 Aug 2025 19:03:19 +0500 Subject: [PATCH 1/3] Init ADR on Rust SDK storage API --- docs/ADR/0024-rust-sdk-storage-api.md | 86 +++++++++++++++++++++++++++ 1 file changed, 86 insertions(+) create mode 100644 docs/ADR/0024-rust-sdk-storage-api.md diff --git a/docs/ADR/0024-rust-sdk-storage-api.md b/docs/ADR/0024-rust-sdk-storage-api.md new file mode 100644 index 0000000..c0e86b4 --- /dev/null +++ b/docs/ADR/0024-rust-sdk-storage-api.md @@ -0,0 +1,86 @@ +# ADR_0024: Rust SDK storage API + +## Date + +Decision date: YYYY-MM-DD +Last status update: YYYY-MM-DD + +## Status + +- [ ] Proposed +- [ ] Accepted +- [ ] Deprecated +- [ ] Superseded + +### Implementation Status + +- [ ] Planned +- [ ] In Development +- [ ] Implemented +- [ ] Verified +- [ ] Discontinued + +## People + +### Author/Decision Owner + +Alisher Khassanov, [@khssnv](https://github.com/khssnv). + +### Consulted + +- Sviatoslav Alekseev, [@zotho](https://github.com/zotho). + +### Informed + +- [ ] Alex Vyatkin, [@actinfer](https://github.com/actinfer). +- [ ] Alexander Lygin, [@alexlygin](https://github.com/AlexLgn). + +## Decision + +We will add an API for on-chain storage. + +## Context + +## Options + +### Option 2: `qf-polkavm-sdk@v0.1.0::safe_api` + +Storage operations with SCALE codec serialization. + +#### Public API + +```rust +// Load user data from contract input +pub fn load_data() -> Result + +// Load value from storage by key +pub fn load(key: &StorageKey) -> Result, LoadError> + +// Save value to storage with key +pub fn save(value: &T, key: &StorageKey) -> Result<(), SaveError> + +// Convert string to storage key +pub fn try_into_key(s: &str) -> Result + +// Storage cell abstraction +struct StorageCell { + pub data: T, + pub storage_key: StorageKey, +} + +impl StorageCell { + pub fn load_from_key(storage_key: K) -> Result, LoadError> + pub fn load(&self) -> Result, LoadError> + pub fn save(&self) -> Result<(), SaveError> +} +``` + +**Rejected because:** + +- Insufficient encapsulation. Similar operations already available in `pallet-revive`'s API'. +- Intended for adding API safety. Irrelevant for already safe API of the `pallet-revive`. + +**Rejected despite:** + +- Automatic SCALE encoding/decoding. +- Simplified `StorageCell` interface. From b7e1b3f5f29f95d94e8c0c0f6536512c3e38ef50 Mon Sep 17 00:00:00 2001 From: "Alisher A. Khassanov" Date: Wed, 1 Oct 2025 19:45:10 +0500 Subject: [PATCH 2/3] Add more options --- docs/ADR/0024-rust-sdk-storage-api.md | 59 +++++++++++++++++++++++---- 1 file changed, 51 insertions(+), 8 deletions(-) diff --git a/docs/ADR/0024-rust-sdk-storage-api.md b/docs/ADR/0024-rust-sdk-storage-api.md index c0e86b4..c1f6925 100644 --- a/docs/ADR/0024-rust-sdk-storage-api.md +++ b/docs/ADR/0024-rust-sdk-storage-api.md @@ -3,7 +3,7 @@ ## Date Decision date: YYYY-MM-DD -Last status update: YYYY-MM-DD +Last status update: 2025-10-01 ## Status @@ -37,16 +37,32 @@ Alisher Khassanov, [@khssnv](https://github.com/khssnv). ## Decision -We will add an API for on-chain storage. +We will add an API for on-chain storage. It will improve storage operations ergonomics. ## Context ## Options +Common properties: + +- Automatic key generation by default. Optional user-defined key. + +### Option 1: TODO + ### Option 2: `qf-polkavm-sdk@v0.1.0::safe_api` Storage operations with SCALE codec serialization. +**Rejected because:** + +- Insufficient encapsulation. Similar operations already available in `pallet-revive`'s API'. +- Intended for adding API safety. Irrelevant for already safe API of the `pallet-revive`. + +**Rejected despite:** + +- Automatic SCALE encoding/decoding. +- Simplified `StorageCell` interface. + #### Public API ```rust @@ -75,12 +91,39 @@ impl StorageCell { } ``` -**Rejected because:** +### Option 3: REST-like -- Insufficient encapsulation. Similar operations already available in `pallet-revive`'s API'. -- Intended for adding API safety. Irrelevant for already safe API of the `pallet-revive`. +Focus on resources and operations on them. +On-chain storage is accessible through an object (similar to an endpoint) with a given set of operations (similar to HTTP verbs). +Could look familiar to frontend engineers. -**Rejected despite:** +```rust +use sdk::storage; -- Automatic SCALE encoding/decoding. -- Simplified `StorageCell` interface. +struct StudentId(u32); +struct Student { + name: String +} + +let alice = Student { name: "Alice".to_string() }; +let id: StudentId = storage::post(alice); + +let mut bob = storage::get(id); + +bob.name = "Bob".to_string(); +storage::put(id, &bob); +``` + +### Option 4: CRUD + +Could look familiar to backend engineers. + +### Option 5: Substrate-like + +The storage layout of the smart contract is defined by a set of structs annotated with a macro that makes them the interface to the on-chain storage. + +## References + +1. Rust API Guidelines, . +1. Elegant Library APIs in Rust, +1. Pragmatic Rust Guidelines, From 2be51702ca29e0e1f2575dd95e1700c5b1ca0922 Mon Sep 17 00:00:00 2001 From: "Alisher A. Khassanov" Date: Thu, 2 Oct 2025 19:58:24 +0500 Subject: [PATCH 3/3] Add GraphQL-like option --- docs/ADR/0024-rust-sdk-storage-api.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/ADR/0024-rust-sdk-storage-api.md b/docs/ADR/0024-rust-sdk-storage-api.md index c1f6925..b84eaae 100644 --- a/docs/ADR/0024-rust-sdk-storage-api.md +++ b/docs/ADR/0024-rust-sdk-storage-api.md @@ -114,11 +114,20 @@ bob.name = "Bob".to_string(); storage::put(id, &bob); ``` -### Option 4: CRUD +### Option 4: GraphQL-like + +GraphQL ideas: schema-first, selection-driven i/o, mutations, partial errors, subscriptions. +Could look familiar to frontend engineers. + +**Rejected because**: + +- Core ideas of the approach address another set of problems and irrelevant for smart contracts case. + +### Option 5: CRUD-like Could look familiar to backend engineers. -### Option 5: Substrate-like +### Option 6: Substrate-like The storage layout of the smart contract is defined by a set of structs annotated with a macro that makes them the interface to the on-chain storage. @@ -127,3 +136,4 @@ The storage layout of the smart contract is defined by a set of structs annotate 1. Rust API Guidelines, . 1. Elegant Library APIs in Rust, 1. Pragmatic Rust Guidelines, +1. GraphQL Core Concepts, .