Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
5f75eba
refactor(sdk): move system contract lookup out of the trusted provider
PastaPastaPasta Oct 21, 2026
0323275
feat(sdk): add opt-in verified HTTP context provider
PastaPastaPasta Oct 21, 2026
313a4a2
fix(sdk): keep verified quorum fetches available under bad input
PastaPastaPasta Oct 21, 2026
abab15a
docs(sdk): document verified provider limits and cache sizing
PastaPastaPasta Oct 21, 2026
5ebe53d
fix(sdk): bound verified quorum fetches that resume after a backoff
PastaPastaPasta Oct 21, 2026
549ab99
fix(sdk): free proof places held by abandoned fetches
PastaPastaPasta Oct 21, 2026
28b0d85
refactor(sdk): simplify the verified context provider
PastaPastaPasta Oct 21, 2026
6435232
refactor(sdk): tell stale proofs apart by error kind
PastaPastaPasta Oct 21, 2026
5c605ec
fix(sdk): release abandoned proof fetches and keep honest heights moving
PastaPastaPasta Oct 21, 2026
9f7864d
fix(sdk): keep a quorum's failures when its next fetch is abandoned
PastaPastaPasta Oct 21, 2026
3e66f31
fix(sdk): cover joined heights and bound live proof fetches
PastaPastaPasta Oct 26, 2026
b254731
fix(sdk): bound each caller's wait and drop relays that stay busy
PastaPastaPasta Oct 26, 2026
6aed756
fix(sdk): let a higher height prove itself after a lower fetch fails
PastaPastaPasta Oct 26, 2026
edc2670
fix(sdk): keep a quorum's higher failure when a lower fetch fails
PastaPastaPasta Oct 26, 2026
fb1d5b1
test(sdk): check that a browser caller's deadline fires
PastaPastaPasta Oct 26, 2026
2b5b548
fix(sdk): serve a quorum key only for heights its proofs bracket
PastaPastaPasta Oct 29, 2026
aa34048
fix(sdk): serve a proven quorum key for one DKG interval past its hig…
PastaPastaPasta Oct 29, 2026
6236bca
build(docker): put llvm-ar on PATH for wasm32 C dependencies
PastaPastaPasta Oct 29, 2026
35841db
ci: run the trusted context provider's tests
PastaPastaPasta Oct 29, 2026
cda0e61
fix(sdk): reject relays that differ only by a trailing slash
PastaPastaPasta Oct 29, 2026
8b28cd2
fix(sdk): refuse a verified provider cache smaller than the active qu…
PastaPastaPasta Oct 31, 2026
076f3f3
fix(sdk): ask for a retired quorum's lower target from the checkpoint
PastaPastaPasta Oct 31, 2026
97ad099
fix(sdk): ask for the lower target from a state below it
PastaPastaPasta Oct 31, 2026
3438180
fix(sdk): keep the last proof request for the lower ask
PastaPastaPasta Oct 31, 2026
ba69ea0
test(sdk): order the proving-place test by its places, not by sleeps
PastaPastaPasta Oct 31, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions .github/package-filters/rs-packages-no-workflows.yml
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ rs-sdk-trusted-context-provider: &sdk_trusted_context_provider
- packages/rs-sdk-trusted-context-provider/**
- *dash_async
- *context_provider
- *core_proof
- *dpp

dapi-grpc: &dapi_grpc
Expand Down
1 change: 1 addition & 0 deletions .github/package-filters/rs-packages.yml
Original file line number Diff line number Diff line change
Expand Up @@ -149,6 +149,7 @@ rs-sdk-trusted-context-provider: &sdk_trusted_context_provider
- packages/rs-sdk-trusted-context-provider/**
- *dash_async
- *context_provider
- *core_proof
- *dpp

dapi-grpc: &dapi_grpc
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/tests-rs-workspace.yml
Original file line number Diff line number Diff line change
Expand Up @@ -460,6 +460,7 @@ jobs:
--package dash-platform-queries \
--package dash-async \
--package dash-core-proof \
--package rs-sdk-trusted-context-provider \
--package platform-value \
--package platform-encryption \
--package rs-dapi \
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -361,6 +361,7 @@ jobs:
- packages/keyword-search-contract/**
- packages/masternode-reward-shares-contract/**
- packages/rs-context-provider/**
- packages/rs-core-proof/**
- packages/rs-dapi-client/**
- packages/rs-dash-async/**
- packages/rs-dash-platform-macros/**
Expand Down
6 changes: 6 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -164,6 +164,9 @@ RUN if [[ "$TARGETARCH" == "arm64" ]] ; then export PROTOC_ARCH=aarch_64; else e
# Note that CC / CXX can be updated later on (eg. when configuring sccache)
RUN rm /usr/bin/cc && \
ln -s /usr/bin/clang /usr/bin/cc
# rs-x11-hash archives its wasm32 build with `llvm-ar`, which Alpine keeps off PATH
RUN ln -s "$(ls -d /usr/lib/llvm*/bin | sort -V | tail -n 1)/llvm-ar" /usr/local/bin/llvm-ar && \
llvm-ar --version
RUN <<EOS
echo "export CXX='clang++'" >> /root/env
echo "export CC='clang'" >> /root/env
Expand Down
25 changes: 24 additions & 1 deletion packages/rs-sdk-trusted-context-provider/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ description = "Trusted HTTP-based context provider for Dash Platform SDK"

dash-async = { path = "../rs-dash-async" }
dash-context-provider = { path = "../rs-context-provider" }
# Verifies the quorum proofs behind `VerifiedHttpContextProvider`.
dash-core-proof = { path = "../rs-core-proof" }
dpp = { path = "../rs-dpp", default-features = false, features = [
"dash-sdk-features",
"bls-signatures",
Expand Down Expand Up @@ -65,6 +67,23 @@ decision-proposals-contract = ["dpp/decision-proposals-contract"]
# Runs the browser's non-`Send` quorum fetches and timers on the local executor.
wasm-bindgen-futures = { version = "0.4.58" }
gloo-timers = { version = "0.3.0", features = ["futures"] }
# Browser `fetch` for proof requests: unlike reqwest on wasm32 it can refuse
# redirects, abort, and bound a body while streaming it.
js-sys = "0.3.85"
wasm-bindgen = "0.2.108"
wasm-streams = "0.5"
web-sys = { version = "0.3.85", features = [
"AbortController",
"AbortSignal",
"Headers",
"ReadableStream",
"Request",
"RequestCache",
"RequestCredentials",
"RequestInit",
"RequestRedirect",
"Response",
] }

[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
# Waits out the gap between two refreshes of the quorum lists.
Expand All @@ -76,5 +95,9 @@ reqwest = { version = "0.12", features = ["json"] }
[target.'cfg(target_os = "android")'.dependencies]
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls-webpki-roots"] }

[dev-dependencies]
[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies]
tokio = { version = "1.40", features = ["macros", "rt-multi-thread"] }

[target.'cfg(target_arch = "wasm32")'.dev-dependencies]
# Runs the browser transport's tests under Node.js or a browser.
wasm-bindgen-test = "0.3.58"
166 changes: 165 additions & 1 deletion packages/rs-sdk-trusted-context-provider/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,9 +117,173 @@ let sdk = SdkBuilder::new(AddressList::default())
.build()?;
```

## Verified Quorum Keys (opt-in)

`VerifiedHttpContextProvider` trusts no HTTP endpoint for quorum keys. It
starts from a checkpoint, a ChainLocked Core block and the masternode and
quorum Merkle roots its coinbase commits to, and accepts a Platform quorum key
only after a Core quorum proof chain (DIP 175, `DASHNC02`) verifies from that
checkpoint and opens the quorum's commitment. Relays that serve the proofs are
untrusted byte sources: a relay that lies, stalls or fails can delay requests,
but cannot make the SDK accept a forged key or ban an honest node.

```rust
use dash_sdk::SdkBuilder;
use dash_sdk::dapi_client::AddressList;
use dpp::dashcore::Network;
use rs_sdk_trusted_context_provider::VerifiedHttpContextProvider;
use std::num::NonZeroUsize;

// Embedded checkpoint, network's public quorum service as the relay.
let provider = VerifiedHttpContextProvider::new(
Network::Testnet,
NonZeroUsize::new(100).expect("cache size"),
)?;

let sdk = SdkBuilder::new(AddressList::default())
.with_context_provider(provider)
.build()?;
```

Your own checkpoint and relays (1 to 8, `https` except on loopback):

```rust
let checkpoint = VerifiedHttpContextProvider::embedded_checkpoint(Network::Testnet)?;
let provider = VerifiedHttpContextProvider::with_checkpoint(
Network::Testnet,
checkpoint,
vec!["https://relay.example.org".to_string()],
NonZeroUsize::new(100).expect("cache size"),
)?;

// Later: persist the newest verified state and start from it next time.
let state_json = serde_json::to_string(&provider.latest_verified_state())?;
```

Behaviour:

- Mainnet and testnet only. Each provider POSTs to `<source>/proofs` with the
checkpoint hash, a height, the quorum hash and type, and `nodeCount: 0`.
- A key is returned for a Core height `H` only when verified proofs show that
the quorum was mined by `H` and active at some height in `[H - 24, H]`:
among the targets whose quorum roots opened the quorum, one is at or below
`H` and one at or above `H - 24` (see the trust model below). Failures of
any kind (timeouts, HTTP errors, oversize or invalid proofs, proofs of
other quorums) are reported as an unavailable quorum source, so the SDK
tries another node without banning the one that named the quorum. A
quorum of another type than the network's Platform quorum type is
rejected as invalid.
- Serving costs about one small proof per 24 Core blocks per quorum in use.
The first proof of a quorum asks for the height itself; Core usually
answers with a target exactly there, since Platform's Core height is
ChainLocked. Past one DKG interval (24 blocks) above the highest proven
target, the relay is usually asked for its latest ChainLock, which serves
the next 24 heights or more. A relay that answers with a target above the
height, because the height has no ChainLock of its own, is asked again for
a target up to 24 blocks below it, which serves the height by itself; the
later target is kept as evidence.
- Fetches of one quorum are shared, and requests for at most two quorums
are in flight at once (a fetch waiting out a backoff gives its place up).
A relay that cannot serve a quorum for two asks (the tip or the height,
then a height 24 blocks below it) is not asked again in that fetch; a busy
relay (503) is retried after a backoff; relays that fail otherwise cool
down, and so does a quorum at a height whose fetch failed. A fetch gives up after 70 s.
Redirects are refused and responses are capped at 1 MiB.
- The cache must hold at least the active Platform quorums (24 on mainnet
and testnet), or the provider is not built; 32 or more avoids proving keys
again just because they were evicted.
- Data contracts come from the known-contracts cache and the system contracts
enabled by cargo features; token configurations from the known cache.
- The public mainnet quorum service currently answers `/proofs` with HTTP 403.
`VerifiedHttpContextProvider::new(Network::Mainnet, ..)` builds, but its
fetches fail until the service serves proofs; pass working mainnet relays
to `with_checkpoint` meanwhile.

### Trust model

What a served key proves: the quorum was mined by the response's Core height
`H`, and active at some height in `[H - 24, H]`. Platform quorums (mainnet
type 4, testnet type 6) do not rotate: the active set at a height is the
newest quorums mined by it, so a quorum enters the set when it is mined and
never returns once it leaves. A quorum in the quorum roots of two verified
targets was therefore active at every height between them. All targets are
proven from one checkpoint through ChainLocks, so they lie on one chain. A
target above `H` is never evidence that the quorum existed at `H`.

The 24 blocks, one DKG interval of the Platform quorum types, cover how Drive
rotates validator sets. It moves off its quorum only at the end of the first
block whose Core height drops that quorum from the active set
(`validator_set_update_v2` in
`packages/rs-drive-abci/src/execution/platform_events/block_end/validator_set_update/v2/mod.rs`),
so that block is still signed by a quorum Core has just rotated out at the
height it reports. The Core height can advance between consecutive Platform
blocks, and the rotation applies only after the block.

The checkpoint is trust configuration, like a hard-coded block hash: whoever
chooses it chooses the chain. Beyond it, the provider trusts that no ChainLock
quorum active at the checkpoint or mined after it ever signs dishonestly,
retired ones included, as `dash-core-proof` documents. A valid proof shows a
quorum was mined, not that its target is the newest ChainLock; how fresh a
response must be is the SDK's policy.

### Checkpoint shelf life

A proof covers every ChainLock quorum rotation between its starting state and
its target, so it grows as the checkpoint ages, and a relay has to keep the
blocks back to it. Each SDK release can move the embedded checkpoints forward.
A long-lived application should persist `latest_verified_state()` and pass it
back to `with_checkpoint` on the next start, so its proofs stay short.

### Limitations

- Keys are proven for the Core height Platform reports in its responses. If
Platform halts, that height stops while Core moves on. A quorum not cached
before the halt is still proven with a proof whose target is that height,
as long as the relay's Core has that ChainLock.
- A height at or below the checkpoint cannot be proven, since every proof
starts from it.
- If the Core height jumps by more than 24 blocks between two Platform blocks,
for example on the first block after a long idle period or a halt, that one
block's responses cannot be verified until the next Platform block. The
provider reports the source as unavailable, so no node is banned.
- A node may name a retired quorum at an old height; it is proven from a
state below that height, possibly the checkpoint. That is bounded by the
same fetch limits and costs only cache churn, not safety.
- An inclusion proof cannot show that a quorum does not exist, so the
provider never reports a quorum as absent; nodes naming fake quorums are
skipped by the SDK, not banned.

### Refreshing the embedded checkpoints

`checkpoints/<network>.json` hold Core `ProofState` JSON (hashes in RPC display
order). To move one to a newer block `H`:

1. Pick a height with `chainlock: true` in `getblock` on two independent Core
nodes, and confirm `getblockhash H` and the block hash on a block explorer
agree.
2. Write the state from the block: `network` (0 mainnet, 1 testnet), `height`,
`block_hash`, and the coinbase payload's `merkleRootMNList` and
`merkleRootQuorums` as `masternode_root` and `quorum_root`.
3. Update `tests/data/checkpoint-evidence-<network>.json`: the raw header
(`getblockheader <hash> false`), the raw coinbase transaction, and the
coinbase's Merkle branch (sibling hashes in wire order). The
`checkpoints` test recomputes the block hash, the header's Merkle root and
both roots from this evidence.

## Implementation Details

The `TrustedHttpContextProvider` implements the `ContextProvider` trait and provides:
Both providers implement the `ContextProvider` trait.

`VerifiedHttpContextProvider` provides:

1. **Quorum Public Keys**: proven from its checkpoint with DIP 175 proofs from
its relays, and kept in an LRU cache
2. **Data Contracts**: pre-loaded or registered known contracts, then the
system contracts enabled by cargo features, otherwise `None`
3. **Token Configurations**: pre-loaded known configurations, otherwise `None`
4. **Platform Activation Height**: hardcoded values for each network

`TrustedHttpContextProvider` provides:

1. **Quorum Public Keys**: Fetched from trusted HTTP endpoints with LRU caching
2. **Data Contracts**:
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"network": 0,
"height": 2550000,
"block_hash": "000000000000000759db5eed70bf470171e7738b85765b395c1a75029c9683ce",
"masternode_root": "1d9ee9f97d3c393c1825c58cec162ffd66efe6a25f24bc4142f68c05b1df1750",
"quorum_root": "1b790dc5600ccfe0f8167412e6b751de8cbac34bcab37ed5feebbb56c117b540"
}
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"network": 1,
"height": 1560000,
"block_hash": "00000215d91d5f3cdfda9de376171ce7eebfeb5adbabc012e8d59501ba07a35e",
"masternode_root": "335e0734bf2efdc117e639e0db433d230042a061b5b17da8462429cf3d11dd80",
"quorum_root": "d1a9305a96f477a0f86be90f2ee4af1085027d5305fd769f2c406dd353114a43"
}
13 changes: 13 additions & 0 deletions packages/rs-sdk-trusted-context-provider/src/error.rs
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
use std::error::Error as StdError;
use thiserror::Error;

#[derive(Error, Debug)]
Expand Down Expand Up @@ -29,3 +30,15 @@ pub enum TrustedContextProviderError {
#[error("Unsupported network: {0}")]
UnsupportedNetwork(String),
}

/// An error with every cause it carries, which `Display` alone leaves out.
pub(crate) fn with_causes(error: &dyn StdError) -> String {
let mut message = error.to_string();
let mut source = error.source();
while let Some(cause) = source {
message.push_str(": ");
message.push_str(&cause.to_string());
source = cause.source();
}
message
}
14 changes: 14 additions & 0 deletions packages/rs-sdk-trusted-context-provider/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,28 @@
//! - **Mainnet**: Uses `https://quorums.mainnet.networks.dash.org/`
//! - **Testnet**: Uses `https://quorums.testnet.networks.dash.org/`
//! - **Devnet**: Uses `https://quorums.<devnet_name>.networks.dash.org/`
//!
//! ## Verified quorum keys
//!
//! [`VerifiedHttpContextProvider`] is an opt-in alternative for mainnet and
//! testnet that trusts no HTTP endpoint: it proves every Platform quorum key
//! from a checkpoint with Core's DIP 175 proofs, and treats the quorum
//! service as an untrusted relay. It lives in this crate because it serves
//! the same applications, talks to the same quorum service and shares the
//! system-contract and HTTP plumbing; the name of the crate predates it.

pub mod error;
mod proof_fetches;
mod proof_transport;
pub mod provider;
mod quorum_refresh;
mod system_contracts;
pub mod types;
pub mod verified_provider;

pub use error::TrustedContextProviderError;
pub use provider::TrustedHttpContextProvider;
pub use verified_provider::{VerifiedContextProviderError, VerifiedHttpContextProvider};

use dpp::dashcore::Network;

Expand Down
Loading
Loading