Skip to main content

Crate pq_bridge_core

Crate pq_bridge_core 

Source
Expand description

§pq-bridge-core

§Experimental / unaudited / testnet only

This crate is research-stage bridge authorization and policy code. It has had no independent cryptographic review or security audit. Use at your own risk. It depends on the RustCrypto ml-dsa crate, which is itself marked unaudited. This crate is not yet recommended for production.

pq-bridge-core is a portable post-quantum bridge-authorization and route policy kit. It verifies ML-DSA-65 committee attestations, computes domain-separated bridge-intent hashes, and enforces route safety policy: drain caps, circuit breakers, cooldown/finality thresholds, trust disclosure, insurance references, and immutable route config after activation.

The API has no Monolythium chain types, no consensus logic, no precompile logic, and no relayer assumptions. It is intended to be embedded by bridge adapters and on-chain contracts, including wasm32-unknown-unknown targets.

This is not a claim to be the first post-quantum bridge. Algorand State Proofs are prior art for post-quantum cross-chain attestation using FALCON. This crate’s scope is narrower: a reusable ML-DSA-65 bridge authorization and policy floor.

§Install

[dependencies]
pq-bridge-core = "0.0.1"

Default features are off. The default build is no_std plus alloc.

§Minimal Usage

use pq_bridge_core::{
    evaluate_policy, verify_attestation, BridgeIntent, OperatorSet, PolicyDecision,
    RouteConfig, RouteState, Threshold,
};

fn verify_route(
    intent: &BridgeIntent,
    sigs: &[(u16, pq_bridge_core::MlDsaSignatureBytes)],
    operators: &OperatorSet,
    cfg: &RouteConfig,
    state: &RouteState,
    now: u64,
) -> bool {
    verify_attestation(intent, sigs, operators, Threshold { k: 3, n: 5 }, now).is_ok()
        && evaluate_policy(cfg, state, intent, now) == PolicyDecision::Allow
}

Operators sign attestation_hash(intent, operators). That binds the canonical bridge intent to the operator epoch and roster hash, so signatures cannot be replayed under a stale committee.

§Safety Model

  • ML-DSA-65 signatures are post-quantum signatures under FIPS 204.
  • The v1 bridge model is committee attestation, not a light client.
  • The route policy is a safety floor, not a full bridge implementation.
  • The relayer is not trusted to enforce policy; callers should enforce policy in the on-chain adapter/contract.
  • Route configuration is immutable after activation by config hash.

§Gates

The release gate is:

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test
cargo build --target wasm32-unknown-unknown
cargo publish --dry-run

§Security

Report security issues privately using the contact path in SECURITY.md.

§License

Apache-2.0. See LICENSE. Crate docs are in the repository README.

Re-exports§

pub use attestation::attestation_hash;
pub use attestation::verify_attestation;
pub use attestation::IndexedSignature;
pub use attestation::MlDsaPublicKeyBytes;
pub use attestation::MlDsaSignatureBytes;
pub use attestation::OperatorSet;
pub use attestation::Threshold;
pub use attestation::ML_DSA_65_PUBLIC_KEY_LEN;
pub use attestation::ML_DSA_65_SIGNATURE_LEN;
pub use error::PolicyError;
pub use error::RouteError;
pub use error::VerifyError;
pub use message::canonical_hash;
pub use message::BridgeIntent;
pub use message::BRIDGE_INTENT_DOMAIN;
pub use policy::apply_drain;
pub use policy::evaluate_policy;
pub use policy::trip_breaker;
pub use policy::PolicyDecision;
pub use route::activate_route;
pub use route::BreakerReason;
pub use route::RouteConfig;
pub use route::RouteState;
pub use route::ROUTE_CONFIG_DOMAIN;

Modules§

attestation
ML-DSA-65 committee attestation verification.
error
Error types for bridge attestation and route-policy evaluation.
message
Canonical bridge intent encoding and replay-bound hashing.
policy
Route policy evaluation and state transitions.
route
Route configuration and mutable route state.