Struct ClientFetchArgs 

pub struct ClientFetchArgs {

    pub node_id: Option<String>,
    pub rediscover: bool,
    pub addr: Option<SocketAddr>,
    pub relay_url: Option<String>,
    pub provider_address: Option<String>,
    pub rpc_url: Option<String>,
    pub payment_pool_address: Option<String>,
    pub slash_judge_address: Option<String>,
    pub capacity_bond_address: Option<String>,
    pub region: Option<String>,
    pub proxy_warming: bool,
    pub proxy_warming_rtt_threshold_ms: u64,
    pub proxy_warming_margin_ms: u64,
    pub max_sources: usize,
    pub give_up_after_secs: Option<u64>,
    pub chain_id: Option<u64>,
    pub keystore: Option<PathBuf>,
    pub keystore_password_file: Option<PathBuf>,
    pub data_dir: Option<PathBuf>,
    pub working_deposit_micro_usdc: Option<u64>,
    pub max_blob_mb: u64,
    pub max_rate_per_mb: u64,
    pub timeout_ms: u64,
    pub capability: Option<String>,
    pub capability_file: Option<PathBuf>,
}

The network, chain, target, and per-blob-limit flags of decdn get, for a blob and a bundle alike. Flattened into super::GetArgs so the resolution (flag > config > default) and node-selection logic have one definition.

Reachability and the required chain coordinates are validated at runtime rather than by clap, because the relay (network.relay_urls, #935) and the chain coordinates ([blockchain]) can come from config, which clap cannot see. --node-id requires --provider-address at the clap layer; the reverse pairing (--provider-address needs --node-id) is enforced in validate(). --addr requires --node-id at the clap layer.

Fields

node_id: Option<String>

Target node id (iroh EndpointId, z-base32). Omit it to auto-discover: the active node set is read from CapacityBond, the region-nearest candidates probed, and one that holds the blob picked (#936). When set, --provider-address is required (they pair).

rediscover: bool

Ignore the persisted peer store for selection this run and re-probe/discover afresh; the store is still updated from what this fetch learns.

addr: Option<SocketAddr>

Direct socket address of the target node (e.g. 127.0.0.1:4433). Only meaningful with an explicit --node-id; auto-discovery resolves the address itself, so this requires --node-id.

relay_url: Option<String>

iroh relay URL to use for discovery-based resolution. Overrides network.relay_urls from config when set (#935).

provider_address: Option<String>

The delivering node’s Ethereum address (0x-prefixed hex). The caller’s pool lane for this provider is opened/reused against it, and the response slash_sig must recover to it (ADR 014 §1); a mismatch aborts the pull. Omit it when auto-discovering (no --node-id): it is derived from the selected node’s registry entry.

Requires --node-id (enforced in validate(), not by clap) — on its own it names no node to dial.

rpc_url: Option<String>

JSON-RPC endpoint for on-chain pool open. Overrides blockchain.rpc_url from config.

payment_pool_address: Option<String>

PaymentPool contract address (0x hex) — the voucher EIP-712 verifyingContract and the openPool target. Overrides blockchain.payment_pool_address.

slash_judge_address: Option<String>

SlashJudge contract address (0x hex) — the slash_sig EIP-712 verifyingContract. Overrides blockchain.slash_judge_address.

capacity_bond_address: Option<String>

CapacityBond contract address (0x hex) — the active-node registry read when auto-discovering (no --node-id). Overrides blockchain.capacity_bond_address. Unused on the explicit-node path.

region: Option<String>

Client region used to prefer same-region nodes when auto-discovering (#936). Matched against each node’s on-chain self-attested region (CapacityBond regionHint, ISO 3166-1 alpha-2 per ADR 030 — e.g. US, DE); case and surrounding whitespace are normalized away, so any spelling of a valid code works. Overrides identity.region; when unset (and no config region), discovery skips the region-first ordering.

Rejected at parse time if it is not an accepted code, so a request for locality never silently degrades to round-robin selection with the flag discarded.

proxy_warming: bool

Latency-driven proxy warming (#1174, ADR 037): on a cache miss whose only holders are distant, route the paid request through a nearer bonded non-holder so it caches the blob and becomes the first regional copy. Engages only when it strictly helps (see --proxy-warming-rtt-threshold-ms / --proxy-warming-margin-ms); otherwise routes direct.

Defaults on (ADR 037 § Fallback). A chosen proxy that declines or stalls is not a regression: it cools, and the fetch carries on from the other candidates and the direct holder over the SAME shared pool (each provider is its own lane, so no new on-chain deposit is escrowed), resuming the partial it already has. The only client-observable cost is a bounded one-request latency premium the first time a locale warms a given blob. Pass --proxy-warming false to route direct and never warm.

proxy_warming_rtt_threshold_ms: u64

Proxy warming engages only when the best holder’s RTT exceeds this many milliseconds (the holders are all distant). Below it, route direct.

proxy_warming_margin_ms: u64

A candidate proxy must beat the best holder’s RTT by at least this many milliseconds to be chosen — proxy warming is never a gamble.

max_sources: usize

Cap on concurrently-used holders (ADR 039): a fetch stripes a blob across at most this many holders at once. Enough to saturate typical downlinks without paying for marginal lanes. It also caps how many holders a bundle’s range-dedup entry stripes its ranges across.

give_up_after_secs: Option<u64>

Stop after this many seconds with no verified progress. Without it, a terminal waits until Ctrl-C and a script stops after 10 minutes.

chain_id: Option<u64>

EIP-712 chainId for both domains. Overrides blockchain.chain_id; defaults to Arbitrum Sepolia.

keystore: Option<PathBuf>

Path to the buyer’s Ethereum keystore that signs vouchers and the openPool tx. Overrides blockchain.eth_keystore; when unset defaults to keystore.json under the (client-scoped) data dir. Password from $DECDN_KEYSTORE_PASSWORD, else --keystore-password-file, else a TTY prompt.

keystore_password_file: Option<PathBuf>

File whose contents are the keystore password. Consulted after the DECDN_KEYSTORE_PASSWORD env var and before an interactive prompt on a TTY. A single trailing newline is stripped; a file that is empty after that strip is a deliberate empty password, not an absent source. A path that does not exist falls through; one that exists but cannot be read is an error.

data_dir: Option<PathBuf>

Data dir holding the persistent buyer pool store (and the default keystore). Overrides identity.data_dir; when unset defaults to the client-scoped ~/.decdn/client (not the node-shaped ~/.decdn).

working_deposit_micro_usdc: Option<u64>

Deposit (µUSDC) to escrow when OPENING a pool, and the target each top-up refills the pool toward once it has served verified bytes. Overrides blockchain.buyer_working_deposit_micro_usdc; default 10 USDC. Must be nonzero (openPool reverts on a zero deposit).

max_blob_mb: u64

Client-side size ceiling: refuse a delivery whose claimed total size exceeds this many MiB before pulling any bytes. Defaults to 1 TiB (1,048,576 MiB) — far above any real blob, so decdn get downloads normal content by its hash without tuning, yet low enough to bound what a provider’s over-claimed total_bytes can cost locally. Lower it as a tighter budget guard, or set 0 to disable the ceiling entirely. For a bundle this is the per-entry ceiling.

The cost it bounds is on disk, not memory: the streaming pull buffers only received bytes in RAM, so RAM stays bounded whatever the claim, and a provider that over-claims total_bytes fails bao verification against the requested hash regardless of this value. But the ranged store pre-sizes a sparse bao outboard sidecar (~0.4% of total_bytes) via set_len at creation, so without a ceiling an absurd claim could surface a local disk or quota error before verification rejects it. This gate caps that pre-size (1 TiB → ~4 GiB) by refusing the claim first.

max_rate_per_mb: u64

Refuse a provider that quotes a per-MB rate above this many USDC base units before paying any voucher (#1375). Guards against a provider that quotes low on the probe then high on the stream. 0 (the default) = no ceiling. For a bundle this applies per entry. Note: unlike the node’s automatic node-to-node pull (which also caps at the candidate’s own probe rate), the CLI applies only this absolute value — set it to opt into buyer rate protection on the client path.

timeout_ms: u64

Hard cap on the total wall-clock time of the CapacityBond registry read (discovery), in milliseconds. Defaults to 1 hour.

It does NOT bound the blob fetch: a progressing pull carries no overall wall-clock cap, so a healthy transfer of any size completes as long as the upstream keeps feeding it bytes (#1134). --give-up-after-secs bounds a fetch that stops making progress.

Exceeding this budget on the registry read (including its retry schedule) is treated as a read failure, so a cached peer list is still used if one is present. It does NOT bound the probe fan-out that ranks candidates either — probing is bounded per node by the probe timeout, not by this flag.

capability: Option<String>

Adopt a delegated pool + capability instead of opening/reusing the caller’s OWN pool. Pass the dcap1: token printed by decdn pool assign: it names the pool and authorizes THIS client’s loaded key to spend against it up to the owner-set cap. The loaded keystore MUST be the delegate signer the token authorizes (a mismatch aborts). The delegate does not own the pool, so its funding recovery step cannot top up: an exhausted cap or a drained pool needs the owner to top up or issue a capability for a new signer key. Mutually exclusive with --capability-file.

capability_file: Option<PathBuf>

Read the dcap1: capability token from a file (its whole trimmed contents) rather than the command line, keeping it out of shell history and the process table. Mutually exclusive with --capability.

Implementations

impl ClientFetchArgs

pub const fn discovery_cap(&self) -> Duration

Wall-clock cap on the CapacityBond registry read, including its ADR 012 retry schedule (#1349): the --timeout-ms value.

A separate budget, not a shared one: sharing would make a bundle’s per-entry fetch depend on how long the read took.

What this does NOT bound

The probe fan-out. A blob fetch probes SELECT_K candidates after the read, and a bundle pull probes per entry; neither is inside this budget. Named here because the obvious reading of “discovery” includes probing, and it does not.

pub const fn give_up_after(&self) -> Option<Duration>

The --give-up-after-secs override of the no-progress limit, or None for the default (a terminal waits, a script stops after 10 minutes).

pub fn validate(&self) -> Result<()>

Reject a flag combination clap cannot express.

Errors

When --provider-address is set without --node-id.

pub fn resolve_capability_token(&self) -> Result<Option<String>>

The dcap1: capability token this fetch adopts, if any: the inline --capability value, or the trimmed contents of --capability-file. None selects the self-owned pool path (unchanged). Clap’s conflicts_with guarantees at most one of the two is set.

Errors

When --capability-file is set but the file cannot be read.

Trait Implementations

impl Args for ClientFetchArgs

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl Clone for ClientFetchArgs

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ClientFetchArgs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for ClientFetchArgs

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.