From bd7809bc17109873213ed2698041974755b351a3 Mon Sep 17 00:00:00 2001 From: Oleksandr Pravdyvyi Date: Fri, 31 Jan 2025 09:54:19 +0200 Subject: [PATCH 1/6] fix: rpc docs added --- README.md | 449 ++++++++++++++++++++++++++++++++++++++ node_core/src/lib.rs | 7 +- sequencer_core/src/lib.rs | 7 +- 3 files changed, 455 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 5e3f2b7..cb77519 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,451 @@ # nescience-testnet This repo serves for Nescience Node testnet + +# How to run +Node and sequecer require Rust installation to build. Preferable latest stable version. + +Rust can be installed as + +```sh +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +``` + +After cloning this repository the following actions need to be done: + +Entrypoints to node and sequencer are `node_runner` and `sequencer_runner`. Both of them have a configuration of similar manner. Path to configs need to be given into runner binaries as first arguent. No other arguments have to be given. We search given directory for files "node_config.json" for node and "sequencer_config.json" for sequencer. + +With repository debug configs at `node_runner/configs/debug` and `sequencer_runner/configs/debug` are provided, you can use them, or modify as you wish. + +For sequencer: + +```yaml +{ + "home": ".", + "override_rust_log": null, + "genesis_id": 1, + "is_genesis_random": true, + "max_num_tx_in_block": 20, + "block_create_timeout_millis": 10000, + "port": 3040 +} +``` + +* "home" shows relative path to directory with datebase. +* "override_rust_log" sets env var "RUST_LOG" to achieve different log levels(if null, using present "RUST_LOG" value). +* "genesis_id" is id of genesis block. +* "is_genesis_random" - flag to randomise forst block. +* "max_num_tx_in_block" - transaction mempool limit. +* "block_create_timeout_millis" - block timeout. +* "port" - port, which sequencer will listen. + +For node: + +```yaml +{ + "home": ".", + "override_rust_log": null, + "sequencer_addr": "http://127.0.0.1:3040", + "seq_poll_timeout_secs": 10, + "port": 3041 +} +``` + +* "home" shows relative path to directory with datebase. +* "override_rust_log" sets env var "RUST_LOG" to achieve different log levels(if null, using present "RUST_LOG" value). +* "sequencer_addr" - address of sequencer. +* "seq_poll_timeout_secs" - polling interval on sequencer, in seconds. +* "port" - port, which sequencer will listen. + +To run: + +_FIRSTLY_ in sequencer_runner directory: + +```sh +RUST_LOG=info cargo run +``` + +_SECONDLY_ in node_runner directory + +```sh +RUST_LOG=info cargo run +``` + +# Node Public API + +Node exposes public API with mutable and immutable methods to create and send transactions. + +## Standards + +Node supports JSON RPC 2.0 standard, details can be seen [there](https://www.jsonrpc.org/specification). + +## API Structure + +Right now API has only one endpoint for every request('/'), and JSON RPC 2.0 standard request structure is fairly simple + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": $string, + "params": $object +} +``` + +Response strucuture will look as follows: + +Success: + +```yaml +{ + "jsonrpc": "2.0", + "result": $object, + "id": "dontcare" +} +``` + +There $number - integer or string "dontcare", $string - string and $object - is some JSON object. + +## Methods + +* get_block + +Get block data for specific block number. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "get_block", + "params": { + "block_id": $number + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "block": $block + }, + "id": $number_or_dontcare +} +``` + +There "block" field returns block for requested block id + +* get_last_block + +Get last block number. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "get_last_block", + "params": {} +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "last_block": $number + }, + "id": $number_or_dontcare +} +``` + +There "last_block" field returns number of last block + +* write_register_account + +Create new acccount with 0 public balance and no private UTXO. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "write_register_account", + "params": {} +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "status": $string + }, + "id": $number_or_dontcare +} +``` + +There "status" field shows address of generated account + +* show_account_public_balance + +Show account public balance, field "account_addr" can be taken from response in "write_register_account" request. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "show_account_public_balance", + "params": { + "account_addr": $string + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "addr": $string, + "balance": $number + }, + "id": $number_or_dontcare +} +``` + +Fields in response is self-explanatory. + +* write_deposit_public_balance + +Deposit public balance into account. Any amount under u64::MAX can be deposited, can overflow. +Due to hashing process(transactions currently does not have randomization factor), we can not send two deposits with same amount to one account. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "write_deposit_public_balance", + "params": { + "account_addr": $string, + "amount": $number + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "status": "success" + }, + "id": $number_or_dontcare +} +``` + +Fields in response is self-explanatory. + +* write_mint_utxo + +Mint private UTXO for account. +Due to hashing process(transactions currently does not have randomization factor), we can not send two mints with same amount to one account. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "write_mint_utxo", + "params": { + "account_addr": $string, + "amount": $number + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "status": "success", + "utxo": { + "asset": [$number], + "commitment_hash": $string, + "hash": $string + } + }, + "id": $number_or_dontcare +} +``` + +There in "utxo" field "hash" is used for viewing purposes, field "commitment_hash" is used for sending purposes. + +* show_account_utxo + +Show UTXO data for account. "utxo_hash" there can be taken from "hash" field in response for "write_mint_utxo" request + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "show_account_utxo", + "params": { + "account_addr": $string, + "utxo_hash": $string + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "amount": $number, + "asset": [$number], + "hash": $string + }, + "id": $number_or_dontcare +} +``` + +Fields in response is self-explanatory. + +* write_send_utxo_private + +Send utxo from one account private balance into another(need to be different) private balance. + +Both parties are is hidden. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "write_send_utxo_private", + "params": { + "account_addr_sender": $string, + "account_addr_receiver": $string, + "utxo_hash": $string, + "utxo_commitment": $string + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "status": "success", + "utxo_result": { + "asset": [$number], + "commitment_hash": $string, + "hash": $string + } + }, + "id": $number_or_dontcare +} +``` + +Be aware, that during this action old UTXO is nullified, hence can not be used anymore, even if present in owner private state. + +* write_send_utxo_deshielded + +Send utxo from one account private balance into another(not neccesary different account) public balance. + +Sender is hidden. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "write_send_utxo_deshielded", + "params": { + "account_addr_sender": $string, + "account_addr_receiver": $string, + "utxo_hash": $string, + "utxo_commitment": $string + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "status": "success" + }, + "id": $number_or_dontcare +} +``` + +Fields in response is self-explanatory. + +* write_send_utxo_shielded + +Send amount from one account public balance into another(not neccesary different account) private balance. + +Receiver is hidden. + +Request: + +```yaml +{ + "jsonrpc": "2.0", + "id": $number_or_dontcare, + "method": "write_send_utxo_shielded", + "params": { + "account_addr_sender": $string, + "account_addr_receiver": $string, + "amount": $number + } +} +``` + +Responce: + +```yaml +{ + "jsonrpc": "2.0", + "result": { + "status": "success", + "utxo_result": { + "asset": [$number], + "commitment_hash": $string, + "hash": $string + } + }, + "id": $number_or_dontcare +} +``` + +Fields in response is self-explanatory. diff --git a/node_core/src/lib.rs b/node_core/src/lib.rs index 2f1469f..e9a862e 100644 --- a/node_core/src/lib.rs +++ b/node_core/src/lib.rs @@ -148,11 +148,10 @@ impl NodeCore { pub async fn get_roots(&self) -> [[u8; 32]; 3] { let storage = self.storage.read().await; - //All roots are non-None after start of node main loop [ - storage.nullifier_store.curr_root.unwrap(), - storage.utxo_commitments_store.get_root().unwrap(), - storage.pub_tx_store.get_root().unwrap(), + storage.nullifier_store.curr_root.unwrap_or([0; 32]), + storage.utxo_commitments_store.get_root().unwrap_or([0; 32]), + storage.pub_tx_store.get_root().unwrap_or([0; 32]), ] } diff --git a/sequencer_core/src/lib.rs b/sequencer_core/src/lib.rs index c6be871..6c87d1f 100644 --- a/sequencer_core/src/lib.rs +++ b/sequencer_core/src/lib.rs @@ -60,11 +60,10 @@ impl SequencerCore { } pub fn get_tree_roots(&self) -> [[u8; 32]; 3] { - //All roots are non-None after start of sequencer main loop [ - self.store.nullifier_store.curr_root.unwrap(), - self.store.utxo_commitments_store.get_root().unwrap(), - self.store.pub_tx_store.get_root().unwrap(), + self.store.nullifier_store.curr_root.unwrap_or([0; 32]), + self.store.utxo_commitments_store.get_root().unwrap_or([0; 32]), + self.store.pub_tx_store.get_root().unwrap_or([0; 32]), ] } From cc3db7d32311bb6d915ad7e5a5eb762291067cf0 Mon Sep 17 00:00:00 2001 From: Oleksandr Pravdyvyi Date: Fri, 31 Jan 2025 10:02:09 +0200 Subject: [PATCH 2/6] fix: format fix --- sequencer_core/src/lib.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/sequencer_core/src/lib.rs b/sequencer_core/src/lib.rs index 6c87d1f..d0163f1 100644 --- a/sequencer_core/src/lib.rs +++ b/sequencer_core/src/lib.rs @@ -62,7 +62,10 @@ impl SequencerCore { pub fn get_tree_roots(&self) -> [[u8; 32]; 3] { [ self.store.nullifier_store.curr_root.unwrap_or([0; 32]), - self.store.utxo_commitments_store.get_root().unwrap_or([0; 32]), + self.store + .utxo_commitments_store + .get_root() + .unwrap_or([0; 32]), self.store.pub_tx_store.get_root().unwrap_or([0; 32]), ] } From c67969efa23522e67a3cf8f8cd8e0dbb8a59dcb3 Mon Sep 17 00:00:00 2001 From: Oleksandr Pravdyvyi Date: Tue, 4 Feb 2025 14:05:42 +0200 Subject: [PATCH 3/6] fix: link added, risc0 toockain install instructions added --- README.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/README.md b/README.md index cb77519..585f2a4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,8 @@ # nescience-testnet This repo serves for Nescience Node testnet +For more details you can read (blogpost)[https://vac.dev/rlog/Nescience-state-separation-architecture/] + # How to run Node and sequecer require Rust installation to build. Preferable latest stable version. @@ -10,6 +12,15 @@ Rust can be installed as curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh ``` +Node needs RISC0 toolchain to run. + +It can be installed as + +```sh +curl -L https://risczero.com/install | bash +rzup install +``` + After cloning this repository the following actions need to be done: Entrypoints to node and sequencer are `node_runner` and `sequencer_runner`. Both of them have a configuration of similar manner. Path to configs need to be given into runner binaries as first arguent. No other arguments have to be given. We search given directory for files "node_config.json" for node and "sequencer_config.json" for sequencer. From d54b0ca556dca0ad328b6b8a927bd4d053edbb30 Mon Sep 17 00:00:00 2001 From: Pravdyvy <46261001+Pravdyvy@users.noreply.github.com> Date: Tue, 4 Feb 2025 14:06:53 +0200 Subject: [PATCH 4/6] fix: fix link --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 585f2a4..68e1ee4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ # nescience-testnet This repo serves for Nescience Node testnet -For more details you can read (blogpost)[https://vac.dev/rlog/Nescience-state-separation-architecture/] +For more details you can read [blogpost](https://vac.dev/rlog/Nescience-state-separation-architecture/) # How to run Node and sequecer require Rust installation to build. Preferable latest stable version. From c1e81538716a9e2c347c5f7b0b0ec6c69fb04e29 Mon Sep 17 00:00:00 2001 From: Oleksandr Pravdyvyi Date: Tue, 4 Feb 2025 14:10:36 +0200 Subject: [PATCH 5/6] fix: more links --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 68e1ee4..2272bea 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ This repo serves for Nescience Node testnet For more details you can read [blogpost](https://vac.dev/rlog/Nescience-state-separation-architecture/) +For more details on node functionality [here](https://www.notion.so/5-Testnet-initial-results-analysis-18e8f96fb65c808a835cc43b7a84cddf) + # How to run Node and sequecer require Rust installation to build. Preferable latest stable version. From 4ecb87658be525f854e86218fb1b600c1fc04b8b Mon Sep 17 00:00:00 2001 From: Pravdyvy <46261001+Pravdyvy@users.noreply.github.com> Date: Tue, 4 Feb 2025 18:20:12 +0200 Subject: [PATCH 6/6] fix: PATH clarification --- README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/README.md b/README.md index 2272bea..b38464b 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,11 @@ It can be installed as ```sh curl -L https://risczero.com/install | bash +``` + +After that, before next step, you may need to restart your console, as script updates PATH variable. Next: + +```sh rzup install ```