Skip to main content

​
Install

The client is the same binary as the node, invoked with client mode: 
decdn client --help
Installation paths (to be finalized at release):
  • Pre-built binaries for Linux (x86_64, aarch64), macOS, Windows
  • cargo install from the published crate
  • Embedded as a library via the published Rust crate

​
First-run initialization

decdn client init \
    --eth-key keychain:com.example.client
This:
  1. Generates an iroh keypair under ~/.decdn/iroh.key.
  2. Configures the L2 network — Arbitrum One (chain ID 42161).
  3. Loads or generates an Ethereum key at the location you specify.
  4. Writes a config at ~/.decdn/config.toml.
The Ethereum key can be:
  • Platform keychain (default) — --eth-key keychain:com.example.client. macOS Keychain, Windows Credential Manager, Gnome Keyring.
  • Hardware wallet — --eth-key ledger:0.
  • Safe smart wallet — --eth-safe 0xSAFEADDRESS (client signs via Safe’s ERC-1271 path; see account management). Recommended for high-frequency or high-value clients.
  • File-based — discouraged. Plaintext keys in the filesystem leak to any process that reads the user’s home directory.

​
Fund your account

Clients pay in any allowlisted ERC-20 (USDC is the reference token) and need a little native gas for on-chain operations. 
decdn client balance
# eth:   0.05 ETH  (Arbitrum One)
# usdc:  50.00 USDC
Any bridge or on-ramp that delivers native USDC (Circle CCTP) to Arbitrum One will work. For other allowlisted tokens, acquire them on Arbitrum One directly.

​
Fetch a blob

decdn client fetch \
    --hash 9fe1c...b2a7 \
    --out ./downloaded.bin \
    --max-budget-usdc 1.00
What happens under the hood:
  1. Bootstrap and peer table population (if not already cached).
  2. DHT FIND_VALUE plus probe fan-out to candidates.
  3. Selection by the unified score.
  4. Channel open with the selected node (auto-sized to fit --max-budget-usdc).
  5. Streaming with BLAKE3 verification.
  6. Vouchers signed on the configured cadence.
  7. Channel close + unspent USDC refund.
Files are verified on receipt — if the stream corrupts, the fetch retries with a different node (losing only the channel deposit consumed so far, minus refund).

​
Common flags

FlagEffect
--max-budget-usdcCap the channel deposit. Unspent amount refunds on close.
--voucher-cadence-mbHow often to sign vouchers (default 1 MB; raise to 10 MB for large files)
--max-channelsMulti-node parallel download (up to 4)
--prefer-regionRegion hint for selection (DE, US, etc.)
--resumeResume from the last BLAKE3-verified byte if a previous fetch crashed

​
Resume after crash

Crash recovery is built in. State is persisted atomically under ~/.decdn/downloads/<hash>/state.json. On --resume, the client:
  • Reads state.json to find the last verified byte offset.
  • Re-probes candidates (the original node may have evicted the blob).
  • Requests StreamRequest { offset_bytes: N }.
  • Continues voucher signing from the persisted nonce.

​
Multi-node parallel download

For large files (>~10 GiB), open multiple channels in parallel: 
decdn client fetch --hash X... --out ./big.bin --max-channels 4
  • One channel per node.
  • Breaks the file into chunks by file manifest; assigns chunks round-robin.
  • Verifies each chunk’s BLAKE3 independently.
  • Net savings grow past ~10 GiB at N=4; below that, single-channel is faster.

​
File manifests

Large files use a manifest blob:
  • The file is split into 256 MiB chunks, each a separate content-addressed blob.
  • A manifest (postcard-encoded) lists the chunk hashes in order.
  • The manifest’s own BLAKE3 hash is the canonical file ID.
Fetching a file = fetch the manifest, then fetch each chunk, verifying each BLAKE3 independently. This lets multi-node parallel download spread work across peers.

​
Next steps