Crate onboarding_bridge 

Onboarding Bridge Contract

A Soroban smart contract that bridges tokens to C-addresses on the Stellar network. It supports single and batch funding, cross-chain onboarding via a multi-sig relayer network, timelocked vesting schedules, a referral fee-split system, and a governance-grade timelocked upgrade path.

Architecture

All state lives in one of two Soroban storage tiers:

• Instance storage — contract-wide singletons (admin, fee config, asset whitelist, relayer threshold, pending upgrade). Extends its TTL on every mutating call.
• Persistent storage — per-address or per-asset data (balances, nonces, daily usage, timelock entries). Extended explicitly via extend_persistent_ttl.

Fee Model

fee       = floor(amount × fee_bps / 10_000)
net       = amount − fee
effective = min(global_fee_bps, asset_fee_cap)
tiered    = looked up by source's cumulative bridged volume

Access Control

Three roles exist:

Role	Stored as	Capabilities
admin	DataKey::Admin	All privileged mutations
fee_collector	DataKey::FeeCollector	withdraw_fees only
relayer set	DataKey::Relayer(pubkey)	Cross-chain attestation

Replay Protection

Two independent mechanisms exist:

1. Sequential nonce (DataKey::Nonce) — optional nonce: Option<u64> parameter on every mutating function. Pass None to skip (standard Stellar transaction replay protection applies). Pass Some(n) to enforce strict ordering.
2. Auth-entry nonce (DataKey::UsedAuthNonce) — used by verify_auth_entry to permanently burn a (source, nonce) pair within a ledger-sequence window, preventing Soroban authorization-entry reuse.

Structs

AssetCounters

Packed per-asset counters stored in a single persistent-storage entry.

BridgeConfig

Packed contract-wide configuration stored in a single instance-storage entry.

BridgeConfigData

Snapshot of admin + fee_collector + fee_bps used during initialization and cached for efficient admin-auth checks in mutating functions.

CommitmentEntry

A pending commit-reveal entry created by commit_fund.

FeeTier

A volume-based fee tier.

MetaFundParams

Parameters for an EIP-712-style meta-transaction fund request.

OnboardingBridge

OnboardingBridgeArgs

OnboardingBridgeArgs is a type for building arg lists for functions defined in “OnboardingBridge”.

OnboardingBridgeClient

OnboardingBridgeClient is a client for calling the contract defined in “OnboardingBridge”.

PendingUpgrade

A scheduled WASM upgrade waiting for its timelock to elapse.

RelayerSig

An Ed25519 signature from a registered relayer.

TimelockEntry

A time-gated funding record created by fund_c_address_timelocked.

Enums

BridgeError

All error codes that the contract may return.

DataKey

Keys used to address every piece of contract state in Soroban storage.

Statics

__SPEC_XDR_TYPE_ASSETCOUNTERS

__SPEC_XDR_TYPE_BRIDGECONFIG

__SPEC_XDR_TYPE_BRIDGECONFIGDATA

__SPEC_XDR_TYPE_BRIDGEERROR

__SPEC_XDR_TYPE_COMMITMENTENTRY

__SPEC_XDR_TYPE_DATAKEY

__SPEC_XDR_TYPE_FEETIER

__SPEC_XDR_TYPE_METAFUNDPARAMS

__SPEC_XDR_TYPE_PENDINGUPGRADE

__SPEC_XDR_TYPE_RELAYERSIG

__SPEC_XDR_TYPE_TIMELOCKENTRY