From e0d92c19fd73d7678c31fb9556d7bcdbd1dadfa7 Mon Sep 17 00:00:00 2001 From: raychu86 Date: Wed, 16 Sep 2020 13:04:06 -0700 Subject: [PATCH 1/5] Add initial account balance md file --- documentation/README.md | 2 +- documentation/aleo/concepts/02_records.md | 8 ++++---- documentation/aleo/concepts/03_transactions.md | 8 ++++---- documentation/aleo/concepts/04_blocks.md | 2 +- documentation/aleo/concepts/06_account_balance.md | 0 .../aleo/concepts/{06_glossary.md => 07_glossary.md} | 0 documentation/developer/programming_model/00_model.md | 4 ++-- documentation/developer/programming_model/01_token.md | 4 ++-- 8 files changed, 14 insertions(+), 14 deletions(-) create mode 100644 documentation/aleo/concepts/06_account_balance.md rename documentation/aleo/concepts/{06_glossary.md => 07_glossary.md} (100%) diff --git a/documentation/README.md b/documentation/README.md index 5954c06e0..dc3b0c706 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -20,7 +20,7 @@ - [Transactions](./aleo/concepts/03_transactions.md) - [Blocks](./aleo/concepts/04_blocks.md) - [Consensus](./aleo/concepts/05_consensus.md) -- [Glossary](./aleo/concepts/06_glossary.md) +- [Glossary](aleo/concepts/07_glossary.md) ## Developer Preview I diff --git a/documentation/aleo/concepts/02_records.md b/documentation/aleo/concepts/02_records.md index 21e3abecb..f14158ecc 100644 --- a/documentation/aleo/concepts/02_records.md +++ b/documentation/aleo/concepts/02_records.md @@ -54,7 +54,7 @@ The **record payload** is a that encodes arbitrary application information. 692575f93ebd4c58e9e6ed288d7ef2328623a8e391224b3cf24c1e65d4f0660ed5d14b78f84a259f14cb24a91fd58386 ``` -The **birth program ID** corresponds to the [birth program](06_glossary.md#birth-program) that must be satisfied when the record is created. +The **birth program ID** corresponds to the [birth program](07_glossary.md#birth-program) that must be satisfied when the record is created. ### Death Program ID @@ -62,7 +62,7 @@ The **birth program ID** corresponds to the [birth program](06_glossary.md#birth 9cb1c71986e72e36640b7fbe09d1853a37bdcbc19a406526a80e54ce37b5c1dd5d14b78f84a259f14cb24746a7fe8b01 ``` -The **death program ID** corresponds to the [death program](06_glossary.md#death-program) that must be specified when the record is spent. +The **death program ID** corresponds to the [death program](07_glossary.md#death-program) that must be specified when the record is spent. ### Serial Number Nonce @@ -70,14 +70,14 @@ The **death program ID** corresponds to the [death program](06_glossary.md#death c8d81ac0028a5643449a80c3cdf8e8f9593ca5e6bcf103b3c33606b01ea20108 ``` -The **serial number nonce** is used to generate a record [record serial number](06_glossary.md#record-serial-number) when the record is being spent. +The **serial number nonce** is used to generate a record [record serial number](07_glossary.md#record-serial-number) when the record is being spent. ### Commitment Randomness ``` 5acbd2c0475c7b4afa72173d7ed800edfc1bde235f5cf4e6c09ef70a36a48a09 ``` -The **commitment randomness** used to generate the [record commitment](06_glossary.md#record-commitment). +The **commitment randomness** used to generate the [record commitment](07_glossary.md#record-commitment). ## Advanced Topics diff --git a/documentation/aleo/concepts/03_transactions.md b/documentation/aleo/concepts/03_transactions.md index 5d6f00456..555b55b89 100644 --- a/documentation/aleo/concepts/03_transactions.md +++ b/documentation/aleo/concepts/03_transactions.md @@ -31,7 +31,7 @@ An Aleo transaction is serialized in the following format: e8a82df9d2e92758f50e52832a0b635718c253ce60962e993afebca9a726de91] ``` -The **old serial numbers** are the [serial numbers](06_glossary.md#record-serial-number) for corresponding records +The **old serial numbers** are the [serial numbers](07_glossary.md#record-serial-number) for corresponding records that were consumed by the transaction. ### New Commitments @@ -41,7 +41,7 @@ that were consumed by the transaction. 2854be536b8ba0feafd10ae0725c1f920aec6b18740607321660b872feac4700] ``` -The **new commitments** are the [commitments](06_glossary.md#record-commitment) for corresponding records that were produced by the transaction. +The **new commitments** are the [commitments](07_glossary.md#record-commitment) for corresponding records that were produced by the transaction. ### Program Commitment @@ -91,7 +91,7 @@ The **network ID** indicates the network that the transaction is included in. Fo 5b74266ae4566ca630c0ce2df1b9bec84c788c6635a40f80e1761dc1bfb0c600f720ea0c6d5e9b8a579e6f00ad6ccfdf916b96b1189c1ff470bfb77d10513703] ``` -The [randomized signatures](06_glossary.md#randomized-signature) used by the record spenders to allow for authorized delegation of transaction generation. +The [randomized signatures](07_glossary.md#randomized-signature) used by the record spenders to allow for authorized delegation of transaction generation. ### Ledger Digest @@ -129,7 +129,7 @@ The steps to create a transaction are as follows: 3. Generate the program commitment 4. Generate the local data commitment 5. Generate the transaction signatures -6. Generate the ledger digest and [ledger membership witnesses](06_glossary.md#ledger-membership-witness) for the input record commitments +6. Generate the ledger digest and [ledger membership witnesses](07_glossary.md#ledger-membership-witness) for the input record commitments 7. Generate the inner SNARK proof 8. Generate the program SNARK proofs 9. Generate the transaction proof diff --git a/documentation/aleo/concepts/04_blocks.md b/documentation/aleo/concepts/04_blocks.md index 1f3e95486..7e15a027a 100644 --- a/documentation/aleo/concepts/04_blocks.md +++ b/documentation/aleo/concepts/04_blocks.md @@ -15,7 +15,7 @@ An Aleo block is serialized in the following format: | Parameter | Type | Size (bytes) | |:----------------:|:------------------------------------------------------------------:|:------------:| | `header` | [Block Header](#components-of-a-block-header) | 503 | -|`num_transactions`| [variable_length_integer](06_glossary.md#variable-length-integer) | `variable` | +|`num_transactions`| [variable_length_integer](07_glossary.md#variable-length-integer) | `variable` | | `transactions` | \[[Transaction](03_transactions.md#components-of-a-transaction)\] | `variable` | #### Block Header diff --git a/documentation/aleo/concepts/06_account_balance.md b/documentation/aleo/concepts/06_account_balance.md new file mode 100644 index 000000000..e69de29bb diff --git a/documentation/aleo/concepts/06_glossary.md b/documentation/aleo/concepts/07_glossary.md similarity index 100% rename from documentation/aleo/concepts/06_glossary.md rename to documentation/aleo/concepts/07_glossary.md diff --git a/documentation/developer/programming_model/00_model.md b/documentation/developer/programming_model/00_model.md index 50d1fcee5..9ca905f1d 100644 --- a/documentation/developer/programming_model/00_model.md +++ b/documentation/developer/programming_model/00_model.md @@ -8,7 +8,7 @@ This section assumes that you have knowledge of [records](../../aleo/concepts/02 ## Leo Record Runtime -Each Leo `.leo` file is compiled into [program](../../aleo/concepts/06_glossary.md#program). +Each Leo `.leo` file is compiled into [program](../../aleo/concepts/07_glossary.md#program). Each program lives in a [record](../../aleo/concepts/02_records.md). Each record lives in a [transaction](../../aleo/concepts/03_transactions.md). An Aleo transaction spends two old records: `old_record_0`, `old_record_1` and creates two new records: `new_record_0`, `new_record_1`. @@ -36,7 +36,7 @@ To ensure the accuracy of input and output register state, a hash of each is sto ## Committing to Register Data. Register values are hashed and included in the [local data commitment](../../aleo/concepts/03_transactions.md#local-data-commitment). -The Leo runtime calculates the [record commitment](../../aleo/concepts/06_glossary.md#record-commitment) as well as +The Leo runtime calculates the [record commitment](../../aleo/concepts/07_glossary.md#record-commitment) as well as the local data commitment to ensure that all record data is included in the [local data root](../../aleo/concepts/03_transactions.md#ledger-digest). ## `.in` and `.out` files diff --git a/documentation/developer/programming_model/01_token.md b/documentation/developer/programming_model/01_token.md index 421e848e5..e17a97ffc 100644 --- a/documentation/developer/programming_model/01_token.md +++ b/documentation/developer/programming_model/01_token.md @@ -26,8 +26,8 @@ The updated [execute](00_model.md#registers) for our example: `old_record_0` contains a token value balance that is transferred entirely into the `new_record_0`. -* `token_debit` is the [death program](../../aleo/concepts/06_glossary.md#death-program) of `old_record_0`. -* `token_credit` is the [birth program](../../aleo/concepts/06_glossary.md#birth-program) of `new_record_0`. +* `token_debit` is the [death program](../../aleo/concepts/07_glossary.md#death-program) of `old_record_0`. +* `token_credit` is the [birth program](../../aleo/concepts/07_glossary.md#birth-program) of `new_record_0`. After `old_record_0` dies, `token_debit` outputs the token id and token value balance `(token_id, value_balance)` being transferred to `new_record_0`. From acb6980b23407ecc486ff494e26083385732a4fa Mon Sep 17 00:00:00 2001 From: raychu86 Date: Wed, 16 Sep 2020 15:04:19 -0700 Subject: [PATCH 2/5] Add initial account balance documentation --- .../aleo/concepts/06_account_balance.md | 89 +++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/documentation/aleo/concepts/06_account_balance.md b/documentation/aleo/concepts/06_account_balance.md index e69de29bb..621d7f19f 100644 --- a/documentation/aleo/concepts/06_account_balance.md +++ b/documentation/aleo/concepts/06_account_balance.md @@ -0,0 +1,89 @@ +# Account Balance + +## Introduction + +Aleo operates under the UTXO model with records that hold balances and program data. An account's balance is the sum +of all the unspent record values that the account owns. Each account is comprised of a `private key`, `proving key`, +`view key`, and `address` as defined [here](./00_accounts.md). + +Every [transaction](./03_transactions.md) spends 2 records and creates 2 new records; these 2 new records are then +encrypted and included in the transaction itself. Each record is encrypted such that only with the record owner's +corresponding [account view key](./00_accounts.md#account-view-key) can decrypt and reason about the record. + +## Owned Records + +Because Aleo is fully private, the user must scan the chain and attempt to decrypt every encrypted record with the +`account view key` to find all the records an `account` owns. Only the `account view key` that successfully decrypts the +record are determined to owned by the corresponding `account address` and spendable by the `account private key`. + +## Spent Records + +Every record has a [commitment](./07_glossary.md#record-commitment) which is revealed when the record is created and a +[serial number](./07_glossary.md#record-serial-number) that is revealed when the record is spent. Each transaction +has 2 `commitment`s and 2 `serial_number`s corresponding to the spending of 2 records and creating of 2 records. +For privacy reasons, the `commitment` and `serial_number` of each record can't be linked unless the user has the +`account private key` that is authorized to spend that particular record. + +To determine if a record has been spent, a user must determine if an owned record's `serial number` already exists +on chain in a transaction by deriving the `serial number` from an owned record and the `account private key` . + +### Determine Account Balance + +Below are the steps to scan the chain and determine an account's balance. + +#### 1. Scan the ledger to find all owned records + +Requirements: `account_view_key` + + 1. Sequentially fetch all the blocks in the ledger + 2. Fetch the transactions in each block + 3. Attempt to decrypt the encryped records in each transaction with a view key + 4. Store the records that can be successfully decrypted + +#### 2. Find Spent Records + + 1. Derive the serial number for each owned record + 2. Sequentially fetch all the blocks in the ledger + 3. Fetch the transactions in each block + 4. Check if the transaction contains a serial number corresponding to one of the owned records + +Note: This step can be done in parallel with [Step 1](#1.-Scan-the-ledger-to-find-all-owned-records) to prevent having to +rescan the entire ledger. + +#### 3. Sum Record Balances + +The account balance is the sum of the values for each owned and unspent record. + +### RPC Interfacing + +Each node has a [JSON-RPC Server](../../autogen/testnet/rpc/concepts/00_rpc_server.md) that can be used to interface and scan the ledger. + + +#### Fetching Blocks + +1. Fetch latest block number, `num_blocks` + - Get the number of blocks with [getblockcount](../../autogen/testnet/public_endpoints/03_getblockcount.md) +2. Fetch every block on the ledger + - For every block number (0 to `num_blocks`) + - Get the block hash with [getblockhash](../../autogen/testnet/public_endpoints/04_getblockhash.md) + - Get the block data with [getblock](../../autogen/testnet/public_endpoints/02_getblock.md) using the block hash + +#### Fetching Transactions + +1. Transaction hashes + - Get the `transactions` field in every [getblock](../../autogen/testnet/public_endpoints/02_getblock.md) call +2. Transaction data + - Get the transaction data with [gettransactioninfo](../../autogen/testnet/public_endpoints/09_gettransactioninfo.md) using the transaction hash + +#### Decrypting Records + +1. Fetch the encrypted record + - Get the `encrypted_records` field in every [gettransactioninfo](../../autogen/testnet/public_endpoints/09_gettransactioninfo.md) call +2. Decryption + - Attempt to decrypt the record with [decryptrecord](../../autogen/testnet/private_endpoints/03_decryptrecord.md) using the `encrypted_record` and an `account view key` + +#### Decoding Records + +1. Record data + - Get the record data with [decoderecord](../../autogen/testnet/private_endpoints/02_decoderecord.md) using + the raw record bytes from the [decryptrecord](../../autogen/testnet/private_endpoints/03_decryptrecord.md) call. From 5e01575de34e162fe5e6cc3f276f439a482f8e5c Mon Sep 17 00:00:00 2001 From: Aleobot Date: Wed, 16 Sep 2020 22:05:00 +0000 Subject: [PATCH 3/5] Sync aleo documentation --- documentation/README.md | 3 ++- documentation/aleo/getting_started/00_overview.md | 3 ++- documentation/autogen/introduction/introduction/00_overview.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/documentation/README.md b/documentation/README.md index dc3b0c706..97ee9d36a 100644 --- a/documentation/README.md +++ b/documentation/README.md @@ -20,7 +20,8 @@ - [Transactions](./aleo/concepts/03_transactions.md) - [Blocks](./aleo/concepts/04_blocks.md) - [Consensus](./aleo/concepts/05_consensus.md) -- [Glossary](aleo/concepts/07_glossary.md) +- [account_balance](./aleo/concepts/06_account_balance.md) +- [Glossary](./aleo/concepts/07_glossary.md) ## Developer Preview I diff --git a/documentation/aleo/getting_started/00_overview.md b/documentation/aleo/getting_started/00_overview.md index 90437c9ea..a5088f48a 100644 --- a/documentation/aleo/getting_started/00_overview.md +++ b/documentation/aleo/getting_started/00_overview.md @@ -27,7 +27,8 @@ to compile, execute, and finalize its state autonomously. - [Transactions](./aleo/concepts/03_transactions.md) - [Blocks](./aleo/concepts/04_blocks.md) - [Consensus](./aleo/concepts/05_consensus.md) -- [Glossary](./aleo/concepts/06_glossary.md) +- [account_balance](./aleo/concepts/06_account_balance.md) +- [Glossary](./aleo/concepts/07_glossary.md) ## Developer Preview I diff --git a/documentation/autogen/introduction/introduction/00_overview.md b/documentation/autogen/introduction/introduction/00_overview.md index 90437c9ea..a5088f48a 100644 --- a/documentation/autogen/introduction/introduction/00_overview.md +++ b/documentation/autogen/introduction/introduction/00_overview.md @@ -27,7 +27,8 @@ to compile, execute, and finalize its state autonomously. - [Transactions](./aleo/concepts/03_transactions.md) - [Blocks](./aleo/concepts/04_blocks.md) - [Consensus](./aleo/concepts/05_consensus.md) -- [Glossary](./aleo/concepts/06_glossary.md) +- [account_balance](./aleo/concepts/06_account_balance.md) +- [Glossary](./aleo/concepts/07_glossary.md) ## Developer Preview I From 359bdee46e1f737e2d50f42a65ffbd36f7ada034 Mon Sep 17 00:00:00 2001 From: raychu86 Date: Wed, 16 Sep 2020 15:21:19 -0700 Subject: [PATCH 4/5] clean up documentation --- documentation/aleo/concepts/06_account_balance.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/documentation/aleo/concepts/06_account_balance.md b/documentation/aleo/concepts/06_account_balance.md index 621d7f19f..46c3800ee 100644 --- a/documentation/aleo/concepts/06_account_balance.md +++ b/documentation/aleo/concepts/06_account_balance.md @@ -33,8 +33,6 @@ Below are the steps to scan the chain and determine an account's balance. #### 1. Scan the ledger to find all owned records -Requirements: `account_view_key` - 1. Sequentially fetch all the blocks in the ledger 2. Fetch the transactions in each block 3. Attempt to decrypt the encryped records in each transaction with a view key From f8798ff801853bca2600f3dd96caaae8edb8750b Mon Sep 17 00:00:00 2001 From: Raymond Chu Date: Thu, 17 Sep 2020 18:26:06 -0700 Subject: [PATCH 5/5] Update 06_account_balance.md --- documentation/aleo/concepts/06_account_balance.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/documentation/aleo/concepts/06_account_balance.md b/documentation/aleo/concepts/06_account_balance.md index 46c3800ee..e1dd69570 100644 --- a/documentation/aleo/concepts/06_account_balance.md +++ b/documentation/aleo/concepts/06_account_balance.md @@ -13,8 +13,9 @@ corresponding [account view key](./00_accounts.md#account-view-key) can decrypt ## Owned Records Because Aleo is fully private, the user must scan the chain and attempt to decrypt every encrypted record with the -`account view key` to find all the records an `account` owns. Only the `account view key` that successfully decrypts the -record are determined to owned by the corresponding `account address` and spendable by the `account private key`. +`account view key` to find all the records an `account` owns. A record is owned by the corresponding `account address` +and spendable by the `account private key` only if the cooresponding `account view key` successfully decrypts the +record. ## Spent Records