Skip to content
LogoLogo

Fibre client brief

This brief covers Fibre clients on celestia-app v10.6.0 (Mocha: v11.0.0-mocha) and celestia-node v0.35.0 (Mocha: v0.36.0-mocha). The rest of this brief was generated from the guide on 2026-10-20. The human guide is the source of truth. Sources live in the guide pages' source comments. If the guide and this brief differ, trust the guide.

How to use this brief

  • Answer only from this brief or the guide files. If it isn't in the guide, say it's unknown. Never invent numbers, SLAs, dates, contacts.
  • Parameters below are the defaults both networks started with at the app v10 upgrade. Governance can change them. Tell users to run celestia-appd query fibre params (REST /fibre/v1/params).

Status

  • Mainnet Beta (celestia): Fibre live (app v10).
  • Mocha (mocha-5, test network): Fibre live (app v10).
  • Activation sources: Mainnet Beta and Mocha. Uploads also require registered, reachable Fibre servers with enough voting power for quorum; activation alone does not prove provider readiness.

Never / always

  • NEVER retry a failed or uncertain upload before checking whether it settled. Each upload = new signed promise = new payment obligation, charged when it settles (PFF or timeout). A promise that reached any validator can be charged via timeout even if the upload failed.
  • NEVER treat a timeout or HTTP 429 during confirmation as a failure. Check settlement first.
  • NEVER describe Fibre as permanent storage. Shards are kept until max(promise creation + shard_retention (4h), promise expiry), then may be deleted. Counted from promise creation, not upload. User must keep their own copy.
  • NEVER claim Fibre checks content correctness. Blob ID binds bytes, not meaning.
  • ALWAYS size escrow ≥ max blobs in flight × charge per blob, plus margin. Validators reserve each accepted promise against available_balance until it settles.
  • ALWAYS save per blob: blob_id, tx_hash, height, namespace, commitment, promise hash (Go), own copy of data.
  • ALWAYS keep the host clock synced. Promise timestamp > 10 min ahead of chain time → rejected.
  • Data is public to anyone with the blob ID. Encrypt sensitive data.

Flow

deposit escrow → client encodes blob, signs payment promise → uploads shards to validators' Fibre servers → each validator stores and signs → at ≥ floor(2/3 × total voting power), client submits MsgPayForFibre (PFF) → chain charges escrow, writes small on-chain blob holding the commitment → anyone downloads by blob ID until retention ends (needs shards from ~1/3 voting power).

Integration options

OptionMax blobNotes
node JSON-RPC fibre.*under 12 MiB (16 MiB request cap, base64)light/bridge node verifies headers
node Go api/client.New128 MiB − 5 Bbuilds a local native client (NewReadClient uses JSON-RPC instead)
celestia-app Go fibre package128 MiB − 5 Bfull control

Node methods: Submit (upload+settle+wait; use first), Upload (settles in background; errors only in node logs), Download, QueryEscrowAccount, Deposit, Withdraw, PendingWithdrawals. Go: fibre.Put = upload+settle+wait, returns tx_hash only after confirmation. For production prefer Client.Upload + own broadcast, saving the hash before confirming. Call Start first; call Stop on shutdown; blob.Free(). A nil keyring allows downloads only. From celestia-app v10.5.0, DetachBackgroundUploads defaults to true. Cancelling after Client.Upload or fibre.Put returns leaves uploads past quorum running, bounded by the RPC timeout and retry limits. Set it false so cancellation stops them. Cancelling before quorum aborts the upload either way. Client.Await, or Client.Stop unless its context is cancelled, waits for the rest. Blob ID: base64 in JSON-RPC. In Go, pass the BlobID ([]byte) as returned; String() = hex, BlobIDFromString parses hex. Same ID.

Money

  • Wallet pays gas. Escrow pays storage. Escrow can't pay gas.
  • Escrow owner = key that signs the promise (secp256k1). Gas for PFF can use fee_granter_address (node).
  • Charge (utia) = 650,000 + 45,000 × ceil(upload_size / 262,144). Fixed formula, not tied to gas price.
  • upload_size = row_size × 4096, where row_size = ceil((len + 5) / 4096) rounded up to a multiple of 64. Minimum 262,144 → minimum charge 0.695 TIA.
  • Examples: 14 B → 0.695 TIA; 10 MiB → 2.495 TIA; 128 MiB − 5 B → 23.69 TIA.
  • Withdrawal paid after withdrawal_delay (24h). Pending withdrawals reduce available_balance immediately.
  • Go Escrow.AutoFund: off by default, works only with fibre.Put.
  • Payments go to the fee collector → validators and delegators.

Limits

ItemValue
Max blob134,217,723 B
Quorum≥ floor(2/3 × total voting power)
Per-validator RPC timeout15 s
Retry on full validator storage3 per validator, wait ≤ 2 min
Validator min upload size262,144 B default; each validator may raise it
PFF1 promise per msg, 1 msg per tx, ≤ 200 per block
shard_retention4h
payment_promise_timeout1h
payment_promise_height_window1000 blocks
withdrawal_delay24h
Promise clock skew≤ 10 min ahead

Errors and action

Validator rejections (escrow, clock, chain ID, min size, storage) appear per validator in client/node logs as failed to upload rows. The upload itself then returns not enough voting power.

Error text containsAction
fibre client is not available / fibre module is not availablenode has no core endpoint → set --core.ip/--core.port
client is not started / client is closedcall Start / create a new client
key not found in keyring / keyring is required for uploadsfix key name / pass a keyring
chain ID mismatchclient and endpoint on different networks
blob size exceeds maximumsplit data
not enough voting power: collected X, required Yquorum missed → diagnose (below); check settlement before retrying
escrow account not founddeposit to the promise signer's escrow
insufficient balance in escrow accounttop up
insufficient available balance for signerin-flight promises exceed escrow → top up or lower concurrency
below local minimumone validator rejects small blobs; fine if quorum is still met
fibre storage budget exceededvalidator full; client retries
creation_timestamp ... must not be afterclock ahead, or chain stalled
payment promise expirednormal settlement ≥ payment_promise_timeout (1h) after creation → upload again if needed; check clock; promise can still be charged via timeout
height ... too far in the pastnormal settlement > payment_promise_height_window (1000) blocks after promise height → upload again if needed; promise can still be charged via timeout
already been processedalready settled → nothing to do
failed to get historical validator settransient; fibre.Put retries; else retry settlement
blob not found: no shards retrievedpast retention, or validators unreachable (network/TLS/provider errors) → within retention check network and retry; after it use own copy
not enough shards to reconstructretry later
invalid blob IDpass ID unchanged (base64 in JSON-RPC; BlobID value in Go)

Diagnose: user's side or network's?

  • All uploads fail with escrow/balance/chain-ID/clock errors → user.
  • Failures across most validators, all timeouts → usually user's egress. Compare from another host.
  • Failures on a few validators only → those validators; ignore while quorum holds.
  • Many validators unreachable, or budget exceeded everywhere → network. Check status.celestia.org and the Mainnet Beta and Mocha Valopers and Tensile dashboards.
  • HTTP 429 from core endpoint → endpoint provider; use own endpoint; check settlement before resubmitting.

Check whether a blob was paid for

  • Have tx_hash → look up the transaction. EventPayForFibre = settled.
  • Have promise hash (hex, Go PaymentPromise.Hash()) → celestia-appd query fibre is-payment-processed <hash>. found: true = charged (normal or timeout).
  • EventPaymentPromiseTimeout with user's escrow_signer = charged without normal settlement.
  • A payment or timeout charge does not by itself attest that the data is available. A successful MsgPayForFibre creates a version-2 system blob in the promise namespace; match its commitment. A timeout charge does not create that blob.

Where details live