prose: finalize accepts empty tx_hashes when every chunk is already stored

[JimCollinson]

Prose update from the daily upstream sweep.

Upstream: ant-sdk: 8378338 → a4accf1

Source artifacts inspected: antd/openapi.yaml (FinalizeUploadRequest.tx_hashes schema), antd/proto/antd/v1/upload.proto (FinalizeUploadRequest.tx_hashes), antd/src/rest/upload.rs (finalize_upload, new resolve_wave_tx_hashes), antd/src/grpc/service.rs (UploadService finalize) — all at a4accf1.

Developer-facing change: for the external-signer wave-batch flow, POST /v1/upload/finalize and the gRPC FinalizeUpload now accept an empty tx_hashes object when the prepare step reported no payments (every chunk already stored on the network — e.g. a repeated upload). Finalize then completes without any on-chain payment and returns the DataMap. An empty map is still rejected when prepare reported payments, and tx_hashes must still be empty for Merkle uploads. The single-chunk finalize (/v1/chunks/finalize, FinalizeChunk) is unchanged.

Files changed in this PR:

• docs/sdk/how-to-guides/use-external-signers-for-upload-payments.md
• docs/sdk/reference/rest-api.md
• docs/sdk/reference/grpc-services.md

Each page's ant-sdk verification stamp is refreshed to a4accf1; the ant-client and evmlib blocks on the how-to page are untouched (those repos did not drift).

Why prose changed:

• use-external-signers-for-upload-payments.md — step 4 gains an empty-tx_hashes finalize example for the all-already-stored case, and step 3 notes there is nothing to submit when prepare returned no payments. Tracks the FinalizeUploadRequest.tx_hashes behaviour in antd/src/rest/upload.rs.
• rest-api.md — the /v1/upload/finalize guidance and examples now cover sending an empty tx_hashes object when prepare reported no payments. Tracks antd/openapi.yaml and antd/src/rest/upload.rs.
• grpc-services.md — the FinalizeUpload tx_hashes field description now records that an empty map is valid for wave-batch when the prepare RPC reported no payments. Tracks antd/proto/antd/v1/upload.proto and antd/src/grpc/service.rs.

Verification run:

• python3 scripts/sweep_poll.py on this branch: status: "ok"; the three edited pages no longer report ant-sdk drift.
• New JSON payloads ({"upload_id":"<hex_id>","tx_hashes":{}}) parse with python3 -m json.tool.
• Prohibited-word and trailing-whitespace scan of the changed lines: clean.
• Envelope check: only docs/**/*.md changed; no scripts/, .github/, registry, or skill-release fields touched. SKILL.md body unchanged, so no linked release.
• Both ant-sdk SHAs fetched into a pinned tmp checkout; the diff was read against a4accf1, never a moving branch.

Uncertainties: none.

🤖 Generated with Claude Code

https://claude.ai/code/session_01A53iW8cysQfKpo2XXasPRJ

---

Generated by Claude Code

[dirvine]

Reviewed the current PR head a198de3b34a25c45841e021c72551dc4a86a73c0 for API accuracy and developer usability.

No blocking correctness or usability findings.

What I verified:

• The documented empty-map contract matches ant-sdk at a4accf1fb617a8b4d8b53e928a279d212411540f: both REST and gRPC inspect the stored prepare result and accept empty tx_hashes only when its expected-payment list is empty. The same shared resolver rejects an empty or incomplete map when payments were expected, before consuming the upload_id.
• The locked ant-core dependency (22f83ffffde41809a139ed5e1aca70cc90e834de) accepts an empty batch/payment map and completes the existing prepared upload path, returning its DataMap and stored-chunk count.
• The REST curl payload and gRPC field guidance are consistent across all three changed pages. The guide makes the no-payment branch explicit before the finalize example, so a reader should not infer that a transaction is still required.
• cargo test -p antd passed all 50 tests, including both empty-map cases and the pre-consume incomplete-map check. The focused ant-core empty-finalization test passed. Repository governance/sweep checks, Markdown links/fences, JSON shape checks, and git diff --check also passed.

Validation limit: I did not run a live network-backed prepare/finalize cycle; antd does not currently have a network-backed gRPC harness for this case. The transport handlers, shared resolver, locked core path, schemas, and deterministic tests were checked directly.

From an accuracy and usability perspective, this is ready to merge.