Skip to main content

regit_web3/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// Copyright (c) 2026 Regit
3
4//! Modular Web3 primitives and typed operations for Rust.
5//!
6//! The catalogue comprises ten chain families: EVM, Solana, Cardano, Bitcoin,
7//! Litecoin, Dogecoin, Bitcoin Cash, XRPL, TON, and `THORChain`; five protocols:
8//! Jupiter, Uniswap, 1inch, LI.FI, and Rubic; and five providers: `CoinGecko`,
9//! `DefiLlama`, Helius, Blockfrost, and mempool.space. All twenty modules provide
10//! functional operations within their documented supported profiles. Authenticated
11//! 1inch live data remains a separate pending check.
12//!
13//! The [`domain`] module provides exact integer amounts and signed decimals,
14//! validated family identities, account values, and attributable observations.
15//! Constructors and deserialization enforce matching invariants. EVM, Solana,
16//! Bitcoin, and Cardano retain distinct identity and context contracts. Bitcoin
17//! records include exact satoshis, signed mempool deltas, bounded history, fees,
18//! and inclusion status; Cardano records include ADA/native assets and bounded
19//! `UTxO` pages. The [`error`] module provides typed failures with fixed diagnostics.
20//!
21//! Default features are empty. Pure family capabilities use standard futures
22//! and allow independently supplied implementations. Their [`future::MaybeSend`]
23//! bound preserves `Send` on native targets and permits host-local JavaScript
24//! futures on `wasm32-unknown-unknown`. Optional concrete
25//! backends supply the necessary RPC/provider access and select their own
26//! runtime and transport dependencies. The `http` feature exposes explicit,
27//! redacted HTTP(S) configuration. Concrete backends use private bounded transport.
28//!
29//! EVM native/ERC-20 balance, allowance, optional metadata and transaction/receipt
30//! status reads use pure capabilities and the optional `evm-http` backend.
31//! State reads verify chain identity, resolve one block, and read with EIP-1898 `blockHash` and
32//! `requireCanonical: true`. Retries retain the captured hash and address without
33//! re-resolving a head or falling back to height. ERC-20 precision is never assumed.
34//! Typed transaction/receipt records retain actual inclusion and distinct execution
35//! outcomes; source JSON identities/signatures are not independently verified.
36//! Nonce and local calls retain canonical state; gas estimates require the
37//! Geth-compatible hash-selector extension without height fallback. Fee facts are
38//! independently sourced. Exact native/ERC-20 preparation retains caller choices
39//! and canonical legacy/type1/type2 signing bytes. Explicit one-shot submission
40//! structurally checks supported signed envelopes and matches the computed hash;
41//! it does not verify signatures/sender/intent or prove acceptance/execution.
42//! Unresolved post-dispatch failures retain possible submission outcome.
43//! Litecoin/Dogecoin provide family-qualified addresses, genesis identities and
44//! exact litoshi/koinu balances with separate signed mempool deltas. Optional
45//! `BlockCypher` mainnet backends read balances, height-cursor history, fee
46//! preferences, complete indexed transactions and status after genesis checks.
47//! Fees are per 1000 serialized bytes; opaque raw bytes and source inclusion do
48//! not establish computed identity, consensus or signature proof.
49//! Bitcoin Cash provides distinct `CashAddr`/legacy and `CashToken` contracts,
50//! full genesis plus explicit fork-checkpoint identity, and six source reads
51//! through optional certificate-verified Electrum-Cash 1.6 TLS. Explicit DER
52//! trust roots, server name and limits select no HTTP dependency. Source history
53//! intervals and zero/null status facts retain actual semantics. Raw bytes have
54//! a computed identity; verbose fields remain separate, without consensus,
55//! signature, raw-field agreement or independently verified inclusion claims.
56//! Solana provides pure identities,
57//! account/balance/observation types, and native/token/account reader contracts.
58//! Maintained legacy/v0/v1 codecs validate canonical structure without verifying
59//! signatures. Ordinary recent-blockhash native/classic SPL preparation retains
60//! last-valid block height in wallet review. Transaction/status, blockhash/height,
61//! message-fee and unsigned-simulation capabilities preserve method-specific
62//! evaluation and inclusion facts. Separate one-shot signed submission sets node
63//! retries to zero and retains unknown post-dispatch outcomes. Seven added methods
64//! have representative mainnet proof: real v1 retrieval and successful unsigned
65//! native simulation; legacy/v0/SPL preparation and submission are fixture-qualified.
66//! Its optional `solana-http` backend verifies the full genesis hash and reads
67//! exact SOL balances, SPL token-account balances, and present/absent accounts.
68//! Read results retain actual slot context. Bitcoin's optional `bitcoin-esplora`
69//! backend verifies the full genesis hash and reads address balances, bounded
70//! history, exact fee estimates, transaction status, and canonical raw/indexed
71//! transaction retrieval. Cardano provides exact indexed records, original-CBOR
72//! body hashing, typed readers and explicit Conway key-spend payment preparation.
73//! The optional `blockfrost-http` backend verifies network magic and implements
74//! seventeen indexed read/estimate methods plus separate one-shot raw-CBOR
75//! submission. Declared fees and failed-script collateral stay separate from
76//! indexed paid fees. Structural witness checks do not verify signatures; source
77//! acknowledgement does not establish execution. Indexed reads do not establish
78//! a hash-selected snapshot or lasting finality. `CoinGecko` provides pure search,
79//! ID/currency price, markets-page and
80//! historical-chart contracts; `coingecko-http` supplies explicit anonymous or
81//! Demo/Pro-header reads with exact prices and independently timed series.
82//! `DefiLlama` provides pure TVL, yield, stablecoin and USD analytics contracts;
83//! `defillama-http` supplies independently configured TVL/analytics, yield and
84//! stablecoin sources. Peg-denominated circulation, USD valuations and percent
85//! APYs remain distinct; large datasets fail at explicit limits without truncation.
86//! Helius provides pure DAS asset and current Parsed Events transaction/history
87//! records with exact raw token units and bounded structured metadata. The
88//! `helius-http` backend verifies full Solana genesis before every read using one
89//! explicit RPC/REST base. Parser outcomes, execution, inclusion slots and DAS
90//! index progress stay distinct; cached prices remain source valuations. Owner
91//! and history continuations retain every original query control, and concrete
92//! handles reject a different client before dispatch. All four methods have
93//! representative authenticated mainnet qualification, including duplicate parsed
94//! batches and successful history records; no signing or submission is provided.
95//! `mempool-space-http` supplies genesis-checked mempool summaries, bounded recent
96//! and full-ID lists, exact sat/vB recommendations and compatible canonical
97//! Bitcoin transaction/status retrieval. Moving observations are independent;
98//! complete lists fail at explicit limits without truncation or invented paging.
99//! TON supplies CRC-checked standard addresses, full zero-state identity, exact
100//! nanotons and bounded maintained BOC/transaction/message representation hashes.
101//! `ton-http` supplies network/account/history/transaction/status/message-scan
102//! reads and explicit wallet-body fee estimates. Account retries freeze the
103//! selected masterchain sequence and check full returned block identity; history
104//! linkage does not prove inclusion. Decoded fees and reported aggregate/outgoing
105//! components remain separate. Optional caller-configured request spacing and
106//! every retry share one deadline. Internal-message preparation supports wallet
107//! review; outer sender/expiry remain unencoded wallet policy. Separate one-shot
108//! submission retains acknowledgment or ambiguous post-dispatch outcome without
109//! retry. Seven reads/estimates and an outgoing-fee transaction have live proof;
110//! submission is fixture-qualified without funded writes or signature verification.
111//! Jupiter V2 supplies quote-only source selection, fresh Metis V0 instructions,
112//! immutable unsigned compilation and external-wallet handoff. Caller CU ceilings,
113//! signer allow-lists and source-other-instruction placement are explicit. Source
114//! instruction/lookup facts do not prove swap semantics. Composed exact-message
115//! Solana fee and unsigned simulation share one deadline and retain separate slots.
116//! Current mainnet quote/build/handoff/estimate have representative live proof;
117//! the public taker returned `AccountNotFound`, without swap-success or submission.
118//! `THORChain` supplies pure Cosmos/asset identities and exact protocol records;
119//! `thorchain-http` supplies RUNE balances, individual/complete layer-one pool
120//! reads, network values, swap quotes, inbound vaults, chain heights and
121//! transaction progress. Cosmos chain ID and account prefix remain separate.
122//! Quotes preserve requested input identity and quantity; the source can expand
123//! identifiers without reporting its resolved input, which remains explicitly
124//! unreported. Full output fee identity
125//! and expiry are checked. Per-chain heights and source stages do not establish
126//! a common snapshot, independent external inclusion or signed execution.
127//! EVM added reads, Litecoin/Dogecoin, Bitcoin Cash, Solana, Bitcoin, XRPL and these provider
128//! backends have representative read-live
129//! qualification; `THORChain` has representative read/quote qualification.
130//! Deterministic fixtures cover each implemented backend. This is point-in-time
131//! source evidence. Cardano/Blockfrost all seventeen indexed reads/estimate and
132//! explicit unsigned review have representative authenticated mainnet proof;
133//! preparation supports protocol majors 9–11. No funded submission was performed.
134//! XRPL provides classic/X-address identities, exact drops and issued values,
135//! source-attributed ledger observations, and ordinary unsigned Payment JSON
136//! preparation. Its `xrpl-http` backend supplies ledger-anchored account/trustline
137//! reads, explicit fee estimates, computed-ID opaque transaction retrieval,
138//! separate execution/inclusion status, and bounded explicit-range account
139//! history. Binary history retains omitted ledger hashes without inventing a
140//! common anchor. Explicit signed-payload submission uses one write attempt and
141//! preserves unresolved outcomes after dispatch; this submit-only path has fixture
142//! qualification, without a funded live submission. Payment preparation covers
143//! ordinary sequence-based XRP/issued transfers; concrete signing and additional
144//! transaction families remain separate extensions.
145//! LI.FI supplies exact-input quotes, bounded route alternatives, selected-step
146//! source preparation and transaction/provider-transfer status. An explicit chain
147//! catalogue prevents family inference from numbers. Immutable selections and
148//! private authority-bound continuations stay separate from fresh estimates and
149//! payloads; encoding does not establish verified signed intent. The four methods
150//! have representative EVM live proof; other family encodings have fixture proof.
151//! Uniswap supplies V3 `QuoterV2` exact-input quotes and bounded comparison of
152//! caller-supplied paths, with one captured canonical EVM hash and total deadline.
153//! Raw output and per-hop prices/ticks remain exact source facts. Pure Universal
154//! Router 2.1.2 preparation retains literal recipient, explicit deadline, exact
155//! slippage floor and separate ERC-20/Permit2 allowance requirements. It supplies
156//! unsigned transaction fields and typed wallet handoff without signing or
157//! submission. V3 quote/comparison have representative live proof; deployment
158//! declarations are caller-verified and no global route discovery is implied.
159//! 1inch supplies Classic Swap v6.1 exact-input EVM quotes, bounded liquidity
160//! catalogues, source spender reads and independent fresh unsigned preparation.
161//! Pure `oneinch` contracts keep exact assets/units, actual graph/filter facts and
162//! immutable original review; `oneinch-http` takes explicit caller-held Bearer
163//! authorization and a replaceable API prefix. Separate spender/fresh reads do
164//! not share a snapshot. Strict ordinary transaction fields retain source gas
165//! suggestions; opaque calldata and estimation overrides do not prove reviewed
166//! intent or execution. Expiry, block and genesis proof are unreported. The four
167//! methods and local handoff have 31 deterministic/loopback tests; authenticated
168//! live qualification remains pending.
169//! Rubic supplies the direct API-v2 chain catalogue, all/best quotes, fresh unsigned
170//! preparation and extended source status. Pure contracts retain caller-qualified
171//! families, exact amounts/fees and bounded JSON source metadata; `rubic-http`
172//! selects a separate outgoing backend. Original selections and explicit caller
173//! constraints remain beside recalculated estimates and EVM/Solana payloads.
174//! Structural checks do not establish calldata/instruction intent, genesis,
175//! expiry or finality. Five operations and EVM review/handoff have representative
176//! native Mac live proof; the supplied unrelated public hash returned `NotFound`.
177//! Solana preparation has fixture proof. Direct preparation does not execute.
178//! The [`wallets`] module supplies generic typed preparation, read-only review and
179//! external handoff. Caller-generated IDs and exact snapshots are correlated
180//! before a trusted caller-supplied verifier checks actual signed-content binding.
181//! Confirmed output has no unchecked constructor or deserialization path. The
182//! `evm` feature supplies canonical transaction preparation; the `xrpl` feature
183//! supplies an ordinary Payment JSON adapter; `uniswap` supplies an unsigned
184//! router-field adapter; `solana` supplies a canonical-message adapter; `ton`
185//! supplies an internal-message adapter; `rubic` composes direct EVM/Solana
186//! preparation with generic review/handoff; `oneinch` retains an unsigned source
187//! envelope and explicit original swap review. Concrete cryptographic
188//! verification, signing, custody and connectors remain separate extensions.
189//! Preparation and handoff do not submit. Authenticated 1inch data remains pending.
190//! Native all-feature library/example builds and offline fixtures passed on Linux,
191//! macOS and Windows at source commit `da1828f` in the
192//! [manual run](https://github.com/org-regit-io/regit-web3/actions/runs/37621428636).
193//! Representative proofs apply to their recorded operations, networks and query variants.
194//!
195//! Read a native balance through an established EVM client:
196//!
197//! ```no_run
198//! # #[cfg(feature = "evm-http")]
199//! # fn main() {
200//! use regit_web3::{
201//!     chains::evm::EvmClient,
202//!     domain::{Address, Balance, BlockSelector, Observation},
203//!     error::Error,
204//! };
205//!
206//! async fn read_balance(
207//!     client: &EvmClient,
208//!     address: Address,
209//! ) -> Result<Observation<Balance>, Error> {
210//!     client.get_native_balance(address, Some(BlockSelector::Safe)).await
211//! }
212//! # }
213//! # #[cfg(not(feature = "evm-http"))]
214//! # fn main() {}
215//! ```
216
217pub mod chains;
218#[cfg(any(feature = "http", feature = "bitcoin-cash-electrum"))]
219pub mod config;
220pub mod domain;
221pub mod error;
222pub mod future;
223pub mod protocols;
224pub mod providers;
225// Compile the private transport when a concrete backend or its tests use it.
226// Extend this predicate as additional integrations are implemented.
227#[cfg(any(
228    all(
229        feature = "bitcoin-cash-electrum",
230        not(all(target_arch = "wasm32", target_os = "unknown"))
231    ),
232    all(
233        feature = "http",
234        any(
235            feature = "evm-http",
236            feature = "solana-http",
237            feature = "bitcoin-esplora",
238            feature = "litecoin-http",
239            feature = "dogecoin-http",
240            feature = "blockfrost-http",
241            feature = "xrpl-http",
242            feature = "coingecko-http",
243            feature = "defillama-http",
244            feature = "mempool-space-http",
245            feature = "thorchain-http",
246            feature = "lifi-http",
247            feature = "ton-http",
248            feature = "helius-http",
249            feature = "rubic-http",
250            feature = "oneinch-http",
251            test
252        )
253    )
254))]
255mod transport;
256pub mod wallets;