Add documentation for account balances

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/06_glossary.md)
+- [account_balance](./aleo/concepts/06_account_balance.md)
+- [Glossary](./aleo/concepts/07_glossary.md)
 
 
 ## Developer Preview I

documentation/aleo/concepts/02_records.md

@@ -54,30 +54,30 @@ 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
 
 ```
 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
 
 ```
 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
 

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

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

documentation/aleo/concepts/06_account_balance.md

@@ -0,0 +1,88 @@
+# 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. 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
+
+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
+
+    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.

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

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

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

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`.