fix(storage): bound 0G upload with a wall-clock timeout

[alkautsarf]

The bug

The 0G SDK's Uploader.waitForLogEntry (@0gfoundation/0g-ts-sdk@1.2.6) is an unbounded while (true) poll that only exits on success. A storage node "stuck at a block" (logSyncHeight stalled) is reachable and answers zgs_getFileInfo with a fast HTTP-200 {result:null} — so it never throws, the SDK's own axios timeout never arms, and the loop spins forever.

OGStorage.putBlob drove that loop (via both indexer.upload and the discovered-nodes splitableUpload) with no timeout. So a wedged mainnet node could pin:

• anima init (keystore upload) — first-time setup hangs forever
• local anima sync
• the daemon POST /sync handler

The download path in the same file was already hardened against exactly this ("a hung indexer or wedged storage node"); the upload path never got the same guard. This was flagged by a friend who hit it building a sibling 0G app, then independently validated (4-investigator + 3-skeptic adversarial pass) against the SDK source.

The fix

Mirror the download-side guard onto the write path:

• Wrap putBlob in Promise.race against a wall-clock deadline (SDK_UPLOAD_TIMEOUT_MS = 120s, configurable via OGStorageOpts.uploadTimeoutMs). A wedged node now throws instead of hanging.
• Swallow the abandoned upload's late rejection (inner.catch) so it can't crash the long-lived daemon as an unhandledRejection. The race still observes a rejection that lands first, so real errors propagate normally (not masked as timeouts).
• Add AbortSignal.timeout(NODE_LIST_TIMEOUT_MS) to the indexer_getShardedNodes fetch, with a clear error translation.

New og.test.ts (5 tests): both upload paths time out, success passes through unchanged, real errors propagate (not masked), and the late rejection is swallowed without an unhandledRejection.

Verification

• typecheck ✓ · lint ✓ · unit 1371/0 · forge 124/0 (all on the main tree)
• Live against 0G testnet: the real upload path ran end-to-end through the wrapper + the new node-list fetch + the gas-balance error translation, and failed fast (~15s, no false-timeout) with the real actionable error — confirming the guard doesn't mask real errors or false-trip a healthy path.

Known trade-offs (documented in code) + deferred follow-ups

The SDK loop is uncancellable (no upstream AbortSignal), so a timed-out upload is abandoned, not stopped. This is bounded, rare (true wedge only), and strictly better than an unbounded hang, but it has follow-ups worth tracking separately:

1. sync-manager doFlush atomicity — it advances lastPlaintextHash per-slot before the batched chain anchor, so a mid-flush putBlob throw (now reachable via timeout) can leave earlier slots marked-uploaded-but-unanchored until daemon restart. Pre-existing for any putBlob throw (e.g. insufficient gas); fix = advance the hash only after the anchor tx.
2. skipIfFinalized: false on the discovered-nodes path means a timeout-then-retry re-submits storage gas even if the first tx finalized. Flip to true to let the SDK dedupe.
3. Uncancellable detached loop — a persistent wedge leaks ~1/s pollers and can double-spend submit gas across the keystore 3x retry. Real deep fix needs upstream SDK abort support.

These are intentionally out of scope for this minimal, well-tested guard.

https://claude.ai/code/session_01JciX2J7DXGGBTDKuvk7q1K

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
anima	Ready	Preview, Comment	Jun 20, 2026 12:06pm

[alkautsarf]

Subsumed by the v0.26.0 release: this work was squash-merged into main as part of commit e27f773 (web-app gateway combined release). Closing as merged-into-main.