Skip to content

feat(adapter): add Zcash data layer - #406

Open
MatiasOS wants to merge 4 commits into
issue-396-connectors-1-8from
issue-398-zcash-core
Open

MatiasOS wants to merge 4 commits into
issue-396-connectors-1-8from
issue-398-zcash-core

Conversation

@MatiasOS

Copy link
Copy Markdown
Member

Description

Adds the Zcash data layer:

  • Domain types.
  • A ZcashAdapter over the Zebra RPC.
  • Wiring so DataService builds that adapter for type: "zcash" networks.

There is no UI yet; the pages land in the next PRs of the stack.

The adapter is designed around hosted gateway limits. Tatum allows about 5 requests per minute per IP and blocks the address index:

  • Blocks: heights go straight to getblock as decimal strings, so one block costs one call, with no getblockhash or header round trip.
  • Failures: a failed call throws a typed ZcashRpcError (unsupported, rateLimited or failed) instead of returning empty data.
    • A rate-limited call is retried after 15s, then after 30s.
  • Addresses: each address section reports its availability (ok, unsupported or error), so pages can degrade when the address index is blocked.
  • Input values: Zebra omits transparent input values. They are resolved on demand, capped at 10 previous transactions.

Related Issue

Part of #398. Stacked on #405.

Type of Change

  • Bug fix
  • New feature
  • Documentation update
  • Refactoring
  • Performance improvement
  • Other (please describe):

Changes Made

  • src/types/index.ts: NetworkType gains "zcash", plus new Zcash types for blocks, transactions, shielded bundles, the mempool and addresses. Amounts are zatoshi integers.
  • src/services/adapters/ZcashAdapter/:
    • The adapter and its transforms.
    • Raw Zebra shapes, including the NU6.3 Ironwood bundle and tree that the connector doesn't model yet.
    • Fixtures trimmed from mainnet block 3,483,400.
  • src/utils/zcashUtils.ts:
    • Address type detection for the t1/t3/tm/t2, zs/ztestsapling, u/utest, zc/zt and tex/textest prefixes.
    • Transaction classification, fee computation from value balances, and RPC error classification.
  • src/utils/zcashFormatters.ts and src/config/zcashConstants.ts.
  • Wiring:
    • AdapterFactory.createZcashAdapter.
    • DataService builds a ZcashClient through ClientFactory (registry routing), and exposes isZcash() and getZcashAdapter().
    • A new isZcashNetwork() helper.
  • MetadataService: Zcash genesis hashes now map to rpcs/zec/{mainnet,testnet}.json. Before, they were dropped because they didn't match the BTC mapping.
  • rpcStorage: built-in Tatum zebrad defaults for both networks.
  • .claude/rules/architecture.md: documents ZcashClient and ZcashAdapter.

Screenshots (if applicable)

N/A (no UI changes)

Checklist

  • I have run npm run format:fix and npm run lint:fix
  • I have run npm run typecheck with no errors
  • I have run tests with npm run test:run
  • I have tested my changes locally
  • I have updated documentation if needed
  • My code follows the project's architecture patterns

Additional Notes

  • Fees on real mainnet transactions:
    • 36a167f6…ce2e3 is Ironwood only, with empty vin and vout. Fee: 10,000 zat.
    • c973d2f1…4aa7db is Sapling plus Ironwood. Fee: 20,000 zat.
  • Tests: 43 new unit tests (27 in zcashUtils.test.ts, 16 in ZcashAdapter.test.ts). The full suite passes with 148 tests.
  • Visibility: nothing is user-visible until the dashboard PR adds the zec and tzec network entries.
  • Upstream gaps in network-connectors:
    • The Ironwood transaction bundle and trees.ironwood aren't modelled.
    • RPC error drops the JSON-RPC error code.

Zebra calls throw a typed ZcashRpcError instead of returning empty data, retry after a 429 with backoff, and report unsupported methods so address pages can degrade on hosted gateways.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant