diff --git a/.gitignore b/.gitignore index c7dbdc2..ab1982c 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ /target /db +/docs/cargo_docs/debug /test_binaries/bins/* /integration-tests/chain_cache/* !/integration-tests/chain_cache/testnet_get_subtree_roots_sapling diff --git a/Cargo.toml b/Cargo.toml index cea4feb..5944df6 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -23,14 +23,14 @@ license = "Apache-2.0" [workspace.dependencies] # Zingolabs +# +# TODO: Move to crate level when updating Zaino-Testutils [https://github.com/zingolabs/zaino/issues/96]. zingolib = { git = "https://github.com/zingolabs/zingolib.git", tag = "zaino_dep_002_091024_95e5b0d8f9d5ee0485c6141533da2f727aeafae2", features = ["zaino-test"] } # Librustzcash zcash_protocol = { git = "https://github.com/zingolabs/librustzcash.git", tag = "zcash_client_sqlite-0.11.2_plus_zingolabs_changes-1-g7ad60b5d5-2-g121371a08" } # Zebra -# -# TODO: Update to release tag once zaino changes PR enters release. zebra-chain = { git = "https://github.com/ZcashFoundation/zebra.git", rev = "4eb285de50848f1a4dcebd0fbe353e4f150fd371" } zebra-rpc = { git = "https://github.com/ZcashFoundation/zebra.git", rev = "4eb285de50848f1a4dcebd0fbe353e4f150fd371" } diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..053fd8f --- /dev/null +++ b/LICENSE @@ -0,0 +1,13 @@ + Copyright 2024 ZingoLabs + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/README.md b/README.md index 1031228..e0fd975 100644 --- a/README.md +++ b/README.md @@ -1,85 +1,48 @@ # Zaino -A rust implemented indexer and lightwallet service for Zcash. +Zaino is an indexer for the Zcash blockchain implemented in Rust. -Zaino is intended to provide all necessary funtionality for clients, including "standalone" (formerly "light") clients/wallets, integrated (formerly "full") client/wallets and block explorers to access both the finalized chain and non-finalized best chain and mempool, held by either a Zebrad or Zcashd full validator. +Zaino provides all necessary functionality for "light" clients (wallets and other applications that don't rely on the complete history of blockchain) and "full" clients / wallets and block explorers providing access both the finalized chain and the non-finalized best chain and mempool held by either a Zebra or Zcashd full validator. -# Security Vulnerability Disclosure -If you believe you have discovered a security issue, please contact us at: - -zingodisclosure@proton.me - -# ZainoD -The Zaino Indexer gRPC service. - -# Zaino-Serve -Holds a gRPC server capable of servicing clients over both https and the nym mixnet (currently removed due to dependecy conflicts). -Also holds the rust implementations of the LightWallet gRPC Service (CompactTxStreamerServer). +### Motivations +With the ongoing Zcashd deprecation project, there is a push to transition to a modern, Rust-based software stack for the Zcash ecosystem. By implementing Zaino in Rust, we aim to modernize the codebase, enhance performance and improve overall security. This work will build on the foundations laid down by [Librustzcash](https://github.com/zcash/librustzcash) and [Zebra](https://github.com/ZcashFoundation/zebra), helping to ensure that the Zcash infrastructure remains robust and maintainable for the future. -# Zaino-Wallet [*Temporarily Removed due to Nym Dependency Conflict] -Holds the nym-enhanced, wallet-side rust implementations of the LightWallet Service RPCs (NymTxStreamerClient). +Due to current potential data leaks / security weaknesses highlighted in [revised-nym-for-zcash-network-level-privacy](https://forum.zcashcommunity.com/t/revised-nym-for-zcash-network-level-privacy/46688) and [wallet-threat-model](https://zcash.readthedocs.io/en/master/rtd_pages/wallet_threat_model.html), there is a need to use anonymous transport protocols (such as Nym or Tor) to obfuscate clients' identities from Zcash's indexing servers ([Lightwalletd](https://github.com/zcash/lightwalletd), [Zcashd](https://github.com/zcash/zcash), Zaino). As Nym has chosen Rust as their primary SDK ([Nym-SDK](https://github.com/nymtech/nym)), and Tor is currently implementing Rust support ([Arti](https://gitlab.torproject.org/tpo/core/arti)), Rust is a straight-forward and well-suited choice for this software. -* Currently only send_transaction and get_lightd_info are implemented over nym. +Zebra has been designed to allow direct read access to the finalized state and RPC access to the non-finalized state through its ReadStateService. Integrating directly with this service enables efficient access to chain data and allows new indices to be offered with minimal development. -# Zaino-State -A mempool and chain-fetching service built on top of zebra's ReadStateService and TrustedChainSync, exosed as a library for direct consumption by full node wallets. +Separation of validation and indexing functionality serves several purposes. First, by removing indexing functionality from the Validator (Zebra) will lead to a smaller and more maintainable codebase. Second, by moving all indexing functionality away from Zebra into Zaino will unify this paradigm and simplify Zcash's security model. Separating this concerns (consensus node and blockchain indexing) serves to create a clear trust boundary between the Indexer and Validator allowing the Indexer to take on this responsibility. Historically, this had been the case for "light" clients/wallets using [Lightwalletd](https://github.com/zcash/lightwalletd) as opposed to "full-node" client/wallets and block explorers that were directly served by the [Zcashd full node](https://github.com/zcash/zcash). -# Zaino-Fetch -A mempool-fetching, chain-fetching and transaction submission service that uses zebra's RPC interface. Used primarily as a backup and legacy option for backwards compatibility. -# Zaino-Nym [*Temporarily Removed due to Nym Dependency Conflict] -Holds backend nym functionality used by Zaino. +### Goals +Our primary goal with Zaino is to serve all non-miner clients -such as wallets and block explorers- in a manner that prioritizes security and privacy while also ensuring the time efficiency critical to a stable currency. We are committed to ensuring that these clients can access all necessary blockchain data and services without exposing sensitive information or being vulnerable to attacks. By implementing robust security measures and privacy protections, Zaino will enable users to interact with the Zcash network confidently and securely. -# Zaino-Proto -Holds tonic generated code for the lightwallet service RPCs and compact formats. +To facilitate a smooth transition for existing users and developers, Zaino is designed (where possible) to maintain backward compatibility with Lightwalletd and Zcashd. This means that applications and services currently relying on these platforms can switch to Zaino with minimal adjustments. By providing compatible APIs and interfaces, we aim to reduce friction in adoption and ensure that the broader Zcash ecosystem can benefit from Zaino's enhancements without significant rewrites or learning curves. -* We plan to eventually rely on LibRustZcash's versions but hold our our here for development purposes. +### Scope +Zaino will implement a comprehensive RPC API to serve all non-miner client requests effectively. This API will encompass all functionality currently in the LightWallet gRPC service ([CompactTxStreamer](https://github.com/zcash/librustzcash/blob/main/zcash_client_backend/proto/service.proto)), currently served by Lightwalletd, and a subset of the [Zcash RPCs](https://zcash.github.io/rpc/) required by wallets and block explorers, currently served by Zcashd. Zaino will unify these two RPC services and provide a single, straightforward interface for Zcash clients and service providers to access the data and services they require. +In addition to the RPC API, Zaino will offer a client library allowing developers to integrate Zaino's functionality directly into their Rust applications. Along with the RemoteReadStateService mentioned below, this will allow both local and remote access to the data and services provided by Zaino without the overhead of using an RPC protocol, and also allows Zebra to stay insulated from directly interfacing with client software. -# Dependencies -1) zebrad -2) lightwalletd [require for testing] -3) zingolib [if running zingo-cli] -4) zcashd, zcash-cli [required until switch to zebras regtest mode] +Currently Zebra's `ReadStateService` only enables direct access to chain data (both Zebra and any process interfacing with the `ReadStateService` must be running on the same hardware). Zaino will extend this functionality, using a Hyper wrapper, to allow Zebra and Zaino (or software built using Zaino's `IndexerStateService` as its backend) to run on different hardware and should enable a much greater range of deployment strategies (eg. running validator, indexer or wallet processes on separate hardware). It should be noted that this will primarily be designed as a remote link between Zebra and Zaino and it is not intended for developers to directly interface with this service, but instead to use functionality exposed by the client library in Zaino (`IndexerStateService`). -# Testing -- To run tests: -1) Simlink or copy compiled `zcashd`, `zcash-cli`, `zebrad` and `lightwalletd` binaries to `$ zaino/test_binaries/bins/*` -2) Run `$ cargo nextest run` or `$ cargo test` +## Documentation +- [Use Cases](./docs/use_cases.md): Holds instructions and example use cases. +- [Testing](./docs/testing.md): Hold intructions fo running tests. +- [Live Service System Architecture](./docs/live_system_architecture.pdf): Holds the Zcash system architecture diagram for the Zaino live service. +- [Library System Architecture](./docs/lib_system_architecture.pdf): Holds the Zcash system architecture diagram for the Zaino client library. +- [Internal Architecture](./docs/internal_architecture.pdf): Holds an internal Zaino system architecture diagram. +- [Internal Specification](./docs/internal_spec.md): Holds a specification for Zaino and its crates, detailing and their functionality, interfaces and dependencies. +- [RPC API Spec](./docs/rpc_api.md): Holds a full specification of all of the RPC services served by Zaino. +- [Cargo Docs](https://zingolabs.github.io/zaino/): Holds a full code specification for Zaino. -- To run client rpc tests: -1) Simlink or copy compiled `zcashd` and `zcash-cli` binaries to `$ zaino/test_binaries/bins/*` -2) Build release binary `cargo build --release` WARNING: these tests do not use the binary built by cargo nextest -3) Generate the chain cache `cargo nextest run generate_zcashd_chain_cach --run-ignored ignored-only --features test_fixtures` -4) Run `cargo nextest run --test client_rpcs` -- To Run client rpc testnet tests i.e. `get_subtree_roots_sapling`: -1) sync Zebrad testnet to at least 2 sapling and 2 orchard shards -2) copy the Zebrad cache to `zaino/integration-tests/chain_cache/testnet_get_subtree_roots_sapling` directory. -3) copy the Zebrad cache to `zaino/integration-tests/chain_cache/testnet_get_subtree_roots_orchard` directory. -See the `get_subtree_roots_sapling` test fixture doc comments in zcash_local_net for more details. - -# Running ZainoD -- To run zingo-cli through Zaino, connecting to zebrad locally: [in seperate terminals] -1) Run `$ zebrad --config #PATH_TO_ZINGO_PROXY/zebrad.toml start` -3) Run `$ cargo run` - -From #PATH_TO/zingolib: -4) Run `$ cargo run --release --package zingo-cli -- --chain "testnet" --server "127.0.0.1:8080" --data-dir ~/wallets/test_wallet` - -# Nym POC [*Temporarily Removed due to Nym Dependency Conflict] -The walletside Nym implementations are moving to ease wallet integration but the POC walletside nym server is still available under the "nym_poc" feature flag. -- To run the POC [in seperate terminals]: -1) Run `$ zebrad --config #PATH_TO_ZINGO_PROXY/zebrad.toml start` -3) Run `$ cargo run` -4) Copy nym address displayed -5) Run `$ cargo run --features "nym_poc" -- ` +## Security Vulnerability Disclosure +If you believe you have discovered a security issue, please contact us at: -From #PATH_TO/zingolib: [send_transaction commands sent with this build will be sent over the mixnet] -6) Run `$ cargo run --release --package zingo-cli -- --chain "testnet" --server "127.0.0.1:8088" --data-dir ~/wallets/testnet_wallet` +zingodisclosure@proton.me -Note: -Configuration data can be set using a .toml file (an example zindexer.toml is given in zingo-indexer/zindexer.toml) and can be set at runtime using the --config arg: -- Run `$ cargo run --config zingo-indexerd/zindexer.toml` +## License +This project is licensed under the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). See the [LICENSE](./LICENSE) file for details. diff --git a/docs/internal_architecture.pdf b/docs/internal_architecture.pdf new file mode 100644 index 0000000..c227f35 Binary files /dev/null and b/docs/internal_architecture.pdf differ diff --git a/docs/internal_spec.md b/docs/internal_spec.md new file mode 100644 index 0000000..f38d330 --- /dev/null +++ b/docs/internal_spec.md @@ -0,0 +1,245 @@ +# Zaino +The Zaino repo consists of several crates that collectively provide an indexing service and APIs for the Zcash blockchain. The crates are modularized to separate concerns, enhance maintainability, and allow for flexible integration. + +The main crates are: + - `Zainod` + - `Zaino-Serve` + - `Zaino-State` + - `Zaino-Fetch` + - `Zaino-Proto` + +### Workspace Dependencies + - `zcash_protocol` + - `zebra-chain` + - `zebra-rpc` + - `tokio` + - `tonic` + - `http` + - `thiserror` + +Below is a detailed specification for each crate. + +A full specification of the public functionality and RPC services available in Zaino is availabe in [Cargo Docs](https://zingolabs.github.io/zaino/index.html) and [RPC API Spec](./rpc_api.md). + + +## ZainoD +`ZainoD` is the main executable that runs the Zaino indexer gRPC service. It serves as the entry point for deploying the Zaino service, handling configuration and initialization of the server components. + +### Functionality +- Service Initialization: + - Parses command-line arguments and configuration files. + - Initializes the gRPC server and internal caching systems using components from `zaino-serve` and `zaino-state` (backed by `zaino-fetch`). + - Sets up logging and monitoring systems. + +- Runtime Management: + - Manages the asynchronous runtime using `Tokio`. + - Handles graceful shutdowns and restarts. + +### Interfaces +- Executable Interface: + - Provides a CLI for configuring the service. (Currently it is only possible to set the conf file path.) + +- Configuration Files: + - Supports TOML files for complex configurations. + +### Dependencies + - `zaino-fetch` + - `zaino-serve` + - `tokio` + - `http` + - `thiserror` + - `serde` + - `ctrlc` + - `toml` + - `clap` + +Full documentation for `ZainoD` can be found [here](https://zingolabs.github.io/zaino/zainod/index.html) and [here](https://zingolabs.github.io/zaino/zainodlib/index.html). + + +## Zaino-Serve +`Zaino-Serve` contains the gRPC server and the Rust implementations of the LightWallet gRPC service (`CompactTxStreamerServer`). It handles incoming client requests and interacts with backend services to fulfill them. + +### Functionality +- gRPC Server Implementation: + - Utilizes `Tonic` to implement the gRPC server. + - Uses a `Director-Ingestor-Worker` model (see [Internal Architecture](./internal_architecture.pdf)) to allow the addition of Nym or Tor based `Ingestors`. + - Dynamically manages the internal Worker pool and Request queue and active Ingestors, handling errors and restarting services where necessary. + - Hosts the `CompactTxStreamerServer` service for client interactions. + +- `CompactTxStreamerServer` Method Implementations: + - Implements the full set of methods as defined in the [LightWallet Protocol](https://github.com/zcash/librustzcash/blob/main/zcash_client_backend/proto/service.proto). + +- Request Handling: + - Validates and parses client requests. + - Communicates with `zaino-state` or `zaino-fetch` to retrieve data. + +- Error Handling: + - Maps internal errors to appropriate gRPC status codes. + - Provides meaningful error messages to clients. + +### Interfaces +- Public gRPC API: + - Defined in `zaino-proto` and exposed to clients. + +- Internal Library: + - The `server::director` module provides the following gRPC server management functions: `ServerStatus::new`, `ServerStatus::load`, `Server::spawn`, `Server::serve`, `Server::check_for_shutdown`, `Server::shutdown`, `Server::status`, `Server::statustype`, `Server::statuses`, `Server::check_statuses`. + - The `server::request` module provides the following request creation and management functions: `TcpRequest::get_stream`, `TcpServerRequest::get_request`, `ZingoIndexerRequest::new_from_grpc`, `ZingoIndexerRequest::increase_requeues`, `ZingoIndexerRequest::duration`, `ZingoIndexerRequest::requeues`. + +### Dependencies + - `zaino-proto` + - `zaino-fetch` + - `zebra-chain` + - `zebra-rpc` + - `tokio` + - `tonic` + - `http` + - `thiserror` + - `prost` + - `hex` + - `tokio-stream` + - `futures` + - `async-stream` + - `crossbeam-channel` + - `lazy-regex` + - `whoami` + +Full documentation for `Zaino-Serve` can be found [here](https://zingolabs.github.io/zaino/zaino_serve/index.html). + + +## Zaino-State +`Zaino-State` is a library that provides access to the mempool and blockchain data by interfacing directly with `Zebra`'s `ReadStateService`. It is designed for direct consumption by full node wallets and internal services. (Currently unimplemented.) + +### Functionality +- Blockchain Data Access: + - Fetches finalized and non-finalized state data. + - Retrieves transaction data and block headers. + - Accesses chain metadata like network height and difficulty. + +- Mempool Management: + - Interfaces with the mempool to fetch pending transactions. + - Provides efficient methods to monitor mempool changes. + +- Chain Synchronization: + - Keeps track of the chain state in sync with Zebra. + - Handles reorgs and updates to the best chain. + +Caching Mechanisms: + - Implements caching for frequently accessed data to improve performance. + +### Interfaces +- Public Library API: + - Provides data retrieval and submission functions that directly correspond to the RPC services offered by `zaino-serve`. + - Provides asynchronous interfaces compatible with `Tokio`. + +- Event Streams: + - Offers highly concurrent, lock-free streams or channels to subscribe to blockchain events. + +### Dependencies + - `zebra-state` + - `tokio` + - `thiserror` + +Full documentation for `Zaino-State` can be found [here](https://zingolabs.github.io/zaino/zaino_state/index.html). + + +## Zaino-Fetch +`Zaino-Fetch` is a library that provides access to the mempool and blockchain data using Zebra's RPC interface. It is primarily used as a backup and for backward compatibility with systems that rely on RPC communication such as `Zcashd`. + +### Functionality +- RPC Client Implementation: + - Implements a `JSON-RPC` client to interact with `Zebra`'s RPC endpoints. + - Handles serialization and deserialization of RPC calls. + +- Data Retrieval and Transaction Submission: + - Fetches blocks, transactions, and mempool data via RPC. + - Sends transactions to the network using the `sendrawtransaction` RPC method. + +- Mempool and CompactFormat access: + - Provides a simple mempool implementation for use in gRPC service implementations. (This is due to be refactored and possibly moved with the development of `Zaino-State`.) + - Provides parse implementations for converting "full" blocks and transactions to "compact" blocks and transactions. + +- Fallback Mechanism: + - Acts as a backup when direct access via `zaino-state` is unavailable. + +### Interfaces +- Internal API: + - The `jsonrpc::connector` module provides the following JSON-RPC client management functions: `new`, `uri`, `url`, `test_node_and_return_uri`. + - The `jsonrpc::connector` module provides the following data retrieval and submission functions: `get_info`, `get_blockchain_info`, `get_address_balance`, `send_raw_transaction`, `get_block`, `get_raw_mempool`, `get_treestate`, `get_subtrees_by_index`, `get_raw_transaction`, `get_address_txids`, `get_address_utxos`. (This may be expanded to match the set of Zcash RPC's that Zaino is taking over from Zcashd.) + - The `chain::block` and `chain::transaction` modules provide the following block and transaction parsing functions: `get_block_from_node`, `get_nullifiers_from_node`, `parse_full_block`, `parse_to_compact`, `FullBlock::to_compact`, `FullTransaction::to_compact`. + - The `chain::mempool` module provides the following mempool management and fetching functions: `new`, `update`, `get_mempool_txids`, `get_filtered_mempool_txids`, `get_best_block_hash`. (This is due to be refactored and possibly moved with the development of `Zaino-State`.) + - Designed to be used by `zaino-serve` transparently. + +### Dependencies + - `zaino-proto` + - `zcash_protocol` + - `zebra-chain` + - `zebra-rpc` + - `tokio` + - `tonic` + - `http` + - `thiserror` + - `prost` + - `reqwest` + - `url` + - `serde_json` + - `serde` + - `hex` + - `indexmap` + - `base64` + - `byteorder` + - `sha2` + +Full documentation for `Zaino-Fetch` can be found [here](https://zingolabs.github.io/zaino/zaino_fetch/index.html). + + +## Zaino-Proto +`Zaino-Proto` contains the `Tonic`-generated code for the LightWallet service RPCs and compact formats. It holds the protocol buffer definitions and the generated Rust code necessary for gRPC communication. + +### Functionality +- Protocol Definitions: + - `.proto` files defining the services and messages for LightWalletd APIs. + - Includes definitions for compact blocks, transactions, and other data structures. + +- Code Generation: + - Uses `prost` to generate Rust types from `.proto` files. + - Generates client and server stubs for gRPC services. + +### Interfaces +- Generated Code: + - Provides Rust modules that can be imported by other crates. + - Exposes types and traits required for implementing gRPC services. + +### Dependencies + - `tonic` + - `prost` + - `tonic-build` + - `which` + +* We plan to eventually rely on `LibRustZcash`'s versions but hold our own here for development purposes. + + +## Zaino-Testutils and Integration-Tests +The `Zaino-Testutils` and `Integration-Tests` crates are dedicated to testing the Zaino project. They provide utilities and comprehensive tests to ensure the correctness, performance, and reliability of Zaino's components. +- `Zaino-Testutils`: This crate contains common testing utilities and helper functions used across multiple test suites within the Zaino project. +- `Integration-Tests`: This crate houses integration tests that validate the interaction between different Zaino components and external services like `Zebra` and `Zingolib`. + +### Test Modules +- `integrations`: Holds Wallet-to-Validator tests that test Zaino's functionality within the compete software stack. +- `client_rpcs`: Holds RPC tests that test the functionality of the LightWallet gRPC services in Zaino and compares the outputs with the corresponding services in `Lightwalletd` to ensure compatibility. + +### Dependencies + - `zaino-fetch` + - `zainod` + - `zingolib` + - `zaino-testutils` + - `zcash_local_net` + - `tokio` + - `tonic` + - `http` + - `ctrlc` + - `tempfile` + - `portpicker` + - `tracing-subscriber` + - `once_cell` + +Full documentation for `Zaino-Testutils` can be found [here](https://zingolabs.github.io/zaino/zaino_testutils/index.html). diff --git a/docs/lib_system_architecture.pdf b/docs/lib_system_architecture.pdf new file mode 100644 index 0000000..767345e Binary files /dev/null and b/docs/lib_system_architecture.pdf differ diff --git a/docs/live_system_architecture.pdf b/docs/live_system_architecture.pdf new file mode 100644 index 0000000..592d917 Binary files /dev/null and b/docs/live_system_architecture.pdf differ diff --git a/docs/nym_poc.pdf b/docs/nym_poc.pdf deleted file mode 100644 index 15313e6..0000000 Binary files a/docs/nym_poc.pdf and /dev/null differ diff --git a/docs/rpc_api.md b/docs/rpc_api.md new file mode 100644 index 0000000..59f173d --- /dev/null +++ b/docs/rpc_api.md @@ -0,0 +1,62 @@ +# Zaino RPC APIs +Zaino's Final RPC API is currently unfinalised and will be completed in this [GitHub Issue](https://github.com/zingolabs/zaino/issues/69). + + +## Lightwallet gRPC Services +Zaino Currently Serves the following gRPC services as defined in the [LightWallet Protocol](https://github.com/zcash/librustzcash/blob/main/zcash_client_backend/proto/service.proto): + - GetLatestBlock (ChainSpec) returns (BlockID) + - GetBlock (BlockID) returns (CompactBlock) + - GetBlockNullifiers (BlockID) returns (CompactBlock) + - GetBlockRange (BlockRange) returns (stream CompactBlock) + - GetBlockRangeNullifiers (BlockRange) returns (stream CompactBlock) + - GetTransaction (TxFilter) returns (RawTransaction) + - SendTransaction (RawTransaction) returns (SendResponse) + - GetTaddressTxids (TransparentAddressBlockFilter) returns (stream RawTransaction) + - GetTaddressBalance (AddressList) returns (Balance) + - GetTaddressBalanceStream (stream Address) returns (Balance) (**MARKED FOR DEPRECATION**) + - GetMempoolTx (Exclude) returns (stream CompactTx) + - GetMempoolStream (Empty) returns (stream RawTransaction) + - GetTreeState (BlockID) returns (TreeState) + - GetLatestTreeState (Empty) returns (TreeState) + - GetSubtreeRoots (GetSubtreeRootsArg) returns (stream SubtreeRoot) + - GetAddressUtxos (GetAddressUtxosArg) returns (GetAddressUtxosReplyList) + - GetAddressUtxosStream (GetAddressUtxosArg) returns (stream GetAddressUtxosReply) + - GetLightdInfo (Empty) returns (LightdInfo) + - Ping (Duration) returns (PingResponse) (**CURRENTLY UNIMPLEMENTED**) + + +## Zcash RPC Services +Zaino has commited to taking over responsibility for serving the following [Zcash RPCs](https://zcash.github.io/rpc/) from Zcashd: + - [getaddressbalance](https://zcash.github.io/rpc/getaddressbalance.html) + - [getaddressdeltas](https://zcash.github.io/rpc/getaddressdeltas.html) + - [getaddressmempool](https://zcash.github.io/rpc/getaddressmempool.html) (**MARKED FOR DEPRECATION**) + - [getaddresstxids](https://zcash.github.io/rpc/getaddresstxids.html) + - [getaddressutxos](https://zcash.github.io/rpc/getaddressutxos.html) + - [getbestblockhash](https://zcash.github.io/rpc/getbestblockhash.html) (**LOW PRIORITY. MARKED FOR POSSIBLE DEPRECATION**) + - [getblock](https://zcash.github.io/rpc/getblock.html) + - [getblockchaininfo](https://zcash.github.io/rpc/getblockchaininfo.html) + - [getblockcount](https://zcash.github.io/rpc/getblockcount.html) + - [getblockdeltas](https://zcash.github.io/rpc/getblockdeltas.html) + - [getblockhash](https://zcash.github.io/rpc/getblockhash.html) + - [getblockhashes](https://zcash.github.io/rpc/getblockhashes.html) + - [getblockheader](https://zcash.github.io/rpc/getblockheader.html) + - [getchaintips](https://zcash.github.io/rpc/getchaintips.html) + - [getdifficulty](https://zcash.github.io/rpc/getdifficulty.html) + - [getmempoolinfo](https://zcash.github.io/rpc/getmempoolinfo.html) + - [getrawmempool](https://zcash.github.io/rpc/getrawmempool.html) + - [getspentinfo](https://zcash.github.io/rpc/getspentinfo.html) + - [gettxout](https://zcash.github.io/rpc/gettxout.html) + - [gettxoutproof](https://zcash.github.io/rpc/gettxoutproof.html) (**LOW PRIORITY. MARKED FOR POSSIBLE DEPRECATION**) + - [gettxoutsetinfo](https://zcash.github.io/rpc/gettxoutsetinfo.html) + - [verifytxoutproof](https://zcash.github.io/rpc/verifytxoutproof.html)(**LOW PRIORITY. MARKED FOR POSSIBLE DEPRECATION**) + - [z_gettreestate](https://zcash.github.io/rpc/z_gettreestate.html) + +Zaino will also provide wrapper functionality for the following RPCs in Zebra (to allow block explorers to fetch all data they require directly from / through Zaino): + - [getinfo](https://zcash.github.io/rpc/getinfo.html) + - [getmininginfo](https://zcash.github.io/rpc/getmininginfo.html) + - [getnetworksolps](https://zcash.github.io/rpc/getnetworksolps.html) + - [getnetworkinfo](https://zcash.github.io/rpc/getnetworkinfo.html) + - [getpeerinfo](https://zcash.github.io/rpc/getpeerinfo.html) + - [ping](https://zcash.github.io/rpc/ping.html) + + diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..4c8d88a --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,24 @@ +# Testing +### Dependencies +1) [Zebrad](https://github.com/ZcashFoundation/zebra.git) +2) [Lightwalletd](https://github.com/zcash/lightwalletd.git) +3) [Zcashd, Zcash-Cli](https://github.com/zcash/zcash) + +### Wallet to Node Tests +- To run tests: +1) Simlink or copy compiled `zcashd`, `zcash-cli`, `zebrad` and `lightwalletd` binaries to `$ zaino/test_binaries/bins/*` +2) Run `$ cargo nextest run --test integrations` + +### Client RPC Tests +- To run client rpc tests: +1) Simlink or copy compiled `zebrad`, zcashd` and `zcash-cli` binaries to `$ zaino/test_binaries/bins/*` +2) Build release binary `cargo build --release` WARNING: these tests do not use the binary built by cargo nextest +3) Generate the chain cache `cargo nextest run generate_zcashd_chain_cach --run-ignored ignored-only --features test_fixtures` +4) Run `cargo nextest run --test client_rpcs` + +- To Run client rpc testnet tests i.e. `get_subtree_roots_sapling`: +1) sync Zebrad testnet to at least 2 sapling and 2 orchard shards +2) copy the Zebrad cache to `zaino/integration-tests/chain_cache/testnet_get_subtree_roots_sapling` directory. +3) copy the Zebrad cache to `zaino/integration-tests/chain_cache/testnet_get_subtree_roots_orchard` directory. +See the `get_subtree_roots_sapling` test fixture doc comments in zcash_local_net for more details. + diff --git a/docs/use_cases.md b/docs/use_cases.md new file mode 100644 index 0000000..b7b18e6 --- /dev/null +++ b/docs/use_cases.md @@ -0,0 +1,33 @@ +# Indexer Live Service +### Dependencies +1) [Zebrad](https://github.com/ZcashFoundation/zebra.git) or [Zcashd, Zcash-Cli](https://github.com/zcash/zcash.git) +2) [Zingolib](https://github.com/zingolabs/zingolib.git) [if running Zingo-Cli] + +### Running ZainoD +- To run a Zaino server, backed locally by Zebrad first build Zaino: +1) Run `$ cargo build --release` +2) Add compiled binary held at `#PATH_TO/zaino/target/release/zainod` to PATH. + +- Then to launch Zaino: [in seperate terminals]: +3) Run `$ zebrad --config #PATH_TO_CONF/zebrad.toml start` +4) Run `$ zainod --config #PATH_TO_CONF/zindexer.toml` + +- To launch Zingo-Cli running through Zaino [from #PATH_TO/zingolib]: +5) Run `$ cargo run --release --package zingo-cli -- --chain "CHAIN_TYPE" --server "ZAINO_LISTEN_ADDR" --data-dir #PATH_TO_WALLET_DATA_DIR` + +- Example Config files for running Zebra and Zaino on testnet are given in `zaino/zainod/*` + +A system architecture diagram for this service can be seen at [Live Service System Architecture](./live_system_architecture.pdf). + + +# Local Library +**Currently Unimplemented, documentation will be added here as this functionality becomes available.** + +A system architecture diagram for this service can be seen at [Library System Architecture](./lib_system_architecture.pdf). + + +# Remote Library +**Currently Unimplemented, documentation will be added here as this functionality becomes available.** + +A system architecture diagram for this service can be seen at [Library System Architecture](./lib_system_architecture.pdf). + diff --git a/docs/zaino_architecture.pdf b/docs/zaino_architecture.pdf deleted file mode 100644 index c92f7d3..0000000 Binary files a/docs/zaino_architecture.pdf and /dev/null differ diff --git a/docs/zaino_zcash_system_architecture.pdf b/docs/zaino_zcash_system_architecture.pdf deleted file mode 100644 index e3ee874..0000000 Binary files a/docs/zaino_zcash_system_architecture.pdf and /dev/null differ