# Z3 - Zaino Index Specification
## Overview
This document contains a high level specifcation of the (proposed) indexes zaino will serve, this will form the basis of the updated zcash gRPC interface post zcashd deprecation, this interface will serve all non-finaliser clients, replacing both the zcash JsonRPC interface as well as the lightwallet gRPC interface.
RPC NOTES:
> There are several miner/validator/finaliser RPCs that Zaino does not currently plan on serving. These could be added to this spec in a "finaliser" module.
> To reduce the resource demands on lightwallet servers, the RPCs essential for lightwallet functionality should be implemented in a dedicated proto module. This separation allows servers to opt out of supporting more data-intensive services, focusing only on lightweight operations.
## Indexes
### 1. Address:
#### 1.1 AddressBalance
**Description:**
> Returns the balance for the given addresses within the given (inclusive) block height range.
**Index Keys:**
> Vec<TransparentAddress>, Option<BlockRange(Height)>.
**Returns:**
> Balance, Recieved.
**Notes:**
> If no blockrange is given data for the whole chain is returned.
---
#### 1.2 AddressDeltas
**Description:**
> Returns information about all changes to the given transparent addresses within the given (inclusive) block height range, default is the full blockchain.
**Index Keys:**
> Vec<TransparentAddress>, Option<BlockRange(Height)>.
**Returns:**
> Stream<Deltas>.
**Notes:**
> If start or end are not specified, they default to zero.
> If start is greater than the latest block height, it's interpreted as that height.
> If end is zero, it's interpreted as the latest block height.
> If no blockrange is given data for the whole chain is returned.
---
#### 1.3 AddressTransactions
**Description:**
> Returns the transactions for given the given transparent addresses within the given (inclusive) block height range, default is the full blockchain.
**Index Keys:**
> Vec<TransparentAddress>, Option<BlockRange(Height)>.
**Returns:**
> Stream<Transaction>.
**Notes:**
> If start or end are not specified, they default to zero.
> If start is greater than the latest block height, it's interpreted as that height.
> If end is zero, it's interpreted as the latest block height.
> If no blockrange is given data for the whole chain is returned.
---
#### 1.4 AddressTxids
**Description:**
> Returns the txids for given the given transparent addresses within the given (inclusive) block height range, default is the full blockchain.
**Index Keys:**
> Vec<TransparentAddress>, Option<BlockRange(Height)>.
**Returns:**
> Stream<Txid>.
**Notes:**
> If start or end are not specified, they default to zero.
> If start is greater than the latest block height, it's interpreted as that height.
> If end is zero, it's interpreted as the latest block height.
> The returned txids are in the order they appear in blocks, which ensures that they are topologically sorted (i.e. parent txids appear before child txids).
> If no blockrange is given data for the whole chain is returned.
---
#### 1.5 AddressUtxos
**Description:**
> Returns all unspent outputs the given addresses.
**Index Keys:**
> Vec<TransparentAddress>, Option<BlockRange(Height)>.
**Returns:**
> Stream<Utxo>.
**Notes:**
> If start or end are not specified, they default to zero.
> If start is greater than the latest block height, it's interpreted as that height.
> If end is zero, it's interpreted as the latest block height.
> If no blockrange is given data for the whole chain is returned.
---
### 2. BlockChain:
#### 2.1 BestBlock
**Description:**
> Returns the hash and height of the best (tip) block in the longest block chain.
**Index Keys:**
>
**Returns:**
> Hash, Height.
**Notes:**
>
---
#### 2.2 Block
**Description:**
> Returns a vec of blocks for the given inclusive block range, formatted according to the specified verbosity level.
- Verbosity = 0: returns a string that is serialized, hex-encoded data for the block.
- Verbosity = 1: returns an Object with information about the block.
- Verbosity = 2: returns an Object with information about the block and information about each transaction.
**Index Keys:**
> BlockRange<HashOrHeight>, Option<Verbosity>.
**Returns:**
> Stream<Block>.
**Notes:**
> Height can be negative where -1 (or None) is the last known valid block.
> Default verbosity = 1 when not given.
> If heights are given, returns blocks in the best chain.
> If hashes are given, returns blocks from all chains.
> If hashes from different chains are given, the block range returned will be of the following format: Start_Block(Hash) -> Fork_Point -> End_Block(Hash).
---
#### 2.3 BlockchainInfo
**Description:**
> Returns an object containing various state info regarding block chain processing.
**Index Keys:**
>
**Returns:**
> BlockChainInfo - TODO!
**Notes:**
>
---
#### 2.4 BlockCount
**Description:**
> Returns the height of the most recent block in the best valid block chain (equivalently, the number of blocks in this chain excluding the genesis block).
**Index Keys:**
>
**Returns:**
> Height.
**Notes:**
>
---
#### 2.5 BlockDeltas
**Description:**
> Returns information about the given block and its transactions.
**Index Keys:**
> Hash.
**Returns:**
> Stream<BlockDeltas> - TODO!
**Notes:**
>
---
#### 2.6 BlockHash
**Description:**
> Returns hash of block in best-block-chain at index provided.
**Index Keys:**
> Height
**Returns:**
> Hash
**Notes:**
> Height can be negative where -1 (or None) is the last known valid block.
---
#### 2.7 BlockHeader
**Description:**
> Returns Block Header data for the given block hash.
**Index Keys:**
> Hash, Option<Vebosity>.
**Returns:**
> BlockHeader.
**Notes:**
> If verbose is false, returns a string that is serialized, hex-encoded data for blockheader 'hash'.
> If verbose is true, returns an Object with information about blockheader <hash>. Default.
---
#### 2.8 ChainTips
**Description:**
> Return information about all known tips in the block tree, including the main chain as well as orphaned branches..
**Index Keys:**
>
**Returns:**
> Vec<BlockId>
**Notes:**
>
---
#### 2.9 CompactBlockData
**Description:**
> > Returns a vec of Compact Blocks for the given inclusive block range, formatted according to the specified verbosity level.
- Verbosity = 0: BlockIndex - TODO.
- Verbosity = 1: Legacy Compact Block.
- Verbosity = 2: Compact Block conaining only nullifiers.
- Verbosity = 3: Compact block with transparent tx data.
**Index Keys:**
> BlockRange<HashOrHeight>, Option<Verbosity>.
**Returns:**
> Stream<CompactBlock>.
**Notes:**
> Height can be negative where -1 (or None) is the last known valid block.
> Default verbosity = 1 when not given.
> If heights are given, returns blocks in the best chain.
> If hashes are given, returns blocks from all chains.
> If hashes from different chains are given, the block range returned will be of the following format: Start_Block(Hash) -> Fork_Point -> End_Block(Hash).
---
#### 2.10 Difficulty
**Description:**
> Returns the proof-of-work difficulty as a multiple of the minimum difficulty.
**Index Keys:**
>
**Returns:**
> n.nnn
**Notes:**
>
---
#### 2.11 TreeState
**Description:**
> Return information about the given block's tree state.
**Index Keys:**
> HashOrHeight
**Returns:**
> TreeState - TODO!
**Notes:**
> Height can be negative where -1 (None) is the last known valid block.
---
#### 2.12 Subtrees
**Description:**
> Returns roots of subtrees of the given pool's note commitment tree. Each value returned in the `subtrees` field is the Merkle root of a subtree containing 2^16 leaves.
**Index Keys:**
> Pool, StartIndex(Height), limit.
**Returns:**
> SubTree(Roots) - TODO!
**Notes:**
>
---
### 3. Control:
#### 3.1 FinalizerInfo
**Description:**
> Returns an object containing various state info from the Validator/Finaliser.
**Index Keys:**
>
**Returns:**
> FinalizerInfo - TODO!
**Notes:**
> Replaces get_info
---
#### 3.2 Z3Info
**Description:**
> Returns an object containing various state info from the Validator/Finaliser and Indexer.
**Index Keys:**
>
**Returns:**
> Z3Info - TODO!
**Notes:**
> replaces get_lightd_info
---
### 4. Mempool:
#### 4.1 MempoolInfo
**Description:**
> Returns details on the active state of the TX memory pool.
**Index Keys:**
>
**Returns:**
> TxCount, TxBytes, MemoryUsage.
**Notes:**
>
---
#### 4.2 MempoolTransactions
**Description:**
> Return the transactions currently in the mempool.
**Index Keys:**
> Option<Vec<Txid>>
**Returns:**
> Vec<Transaction> (Exclude List)
**Notes:**
> If the Exclude list is empty, return all transactions; otherwise return all *except* those in the Exclude list (if any); this allows the client to avoid receiving transactions that it already has (from an earlier call to this rpc).
> The transaction IDs in the exclude list can be shortened to any number of bytes to make the request more bandwidth-efficient; if two or more transactions in the mempool match a shortened txid, they are all sent (none is excluded). Transactions in the exclude list that don't exist in the mempool are ignored.
---
#### 4.3 MempoolStream
**Description:**
> Returns a stream of Mempool transactions, closing the stream when there is a new chain tip.
**Index Keys:**
> Option<Hash>
**Returns:**
> Stream<Transactions>
**Notes:**
> If Hash is given and does not match the hash of the current chain tip an IncorrectTip error will be returned.
---
### 5. Mining:
#### 5.1 BlockSubsidy
**Description:**
> Returns block subsidy reward, taking into account the mining slow start and the founders reward, of block at index provided.
**Index Keys:**
> Option<Height>
**Returns:**
> Subsidy - TODO!
**Notes:**
> Defaults to best chain tip if no height is provided.
---
#### 5.2 MiningInfo
**Description:**
> Returns a json object containing mining-related information.
**Index Keys:**
>
**Returns:**
> MiningInfo - TODO!
**Notes:**
>
---
#### 5.3 NetworkSolps
**Description:**
> Returns the estimated network solutions per second based on the last n blocks.
**Index Keys:**
> Option<Blocks>, Option<Height>.
**Returns:**
> SolutionsPerSecond
**Notes:**
> Pass in [blocks] to override # of blocks, -1 specifies over difficulty averaging window. Defaults to 120.
> Pass in [height] to estimate the network speed at the time when a certain block was found. Default = -1.
---
### 6. Network:
#### 6.1 NetworkInfo
**Description:**
> Returns an object containing various state info regarding P2P networking.
**Index Keys:**
>
**Returns:**
> NetworkInfo - TODO!
**Notes:**
>
---
#### 6.2 PeerInfo
**Description:**
> Returns data about each connected network node as a json array of objects.
**Index Keys:**
>
**Returns:**
> PeerInfo - TODO!
**Notes:**
>
---
#### 6.3 Ping
**Description:**
> Requests that a ping be sent to all other nodes, to measure ping time.
**Index Keys:**
>
**Returns:**
> Pingtime, Pingwait.
**Notes:**
> Results provided in getpeerinfo.
> Pingtime and Pingwait fields are decimal seconds.
> Ping command is handled in queue with all other commands, so it measures processing backlog, not just network ping.
---
### 7. Transaction:
#### 7.1 Transaction
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
---
#### 7.2 TxOut
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
---
#### 7.3 TxOutSetInfo
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
---
#### 7.4 SendTransaction - **NOT FETCH**
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
---
#### 7.5 SpendTransactionId
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
---
#### 7.6 SpentInfo
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
---
### 8. Util:
#### 8.1 ValidateAddress
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
---
#### 8.2 ZValidateAddress
**Description:**
> What this index is for.
**Index Keys:**
> Primary lookup keys.
**Returns:**
> High-level data returned.
**Notes:**
> (Optional) Additional clarifications, constraints, etc.
Sign in with Wallet
Connect another wallet