Skip to content

feat: add escrow withdrawal support - #186

Draft
tnunamak wants to merge 8 commits into
mainfrom
tim/escrow-withdraw-sdk-0811
Draft

feat: add escrow withdrawal support#186
tnunamak wants to merge 8 commits into
mainfrom
tim/escrow-withdraw-sdk-0811

Conversation

@tnunamak

@tnunamak tnunamak commented Aug 11, 2026

Copy link
Copy Markdown
Member

Adds SDK support for Data Gateway escrow withdrawals on top of the current paid-read SDK surface.

Scope

  • Adds EIP-712 helpers for WithdrawAuthorization messages with account, asset, amount, withdrawNonce, and deadline.
  • Adds EscrowGatewayClient.withdraw with typed submitted, confirmed, finalized, retryable, reorged, and failed lifecycle results.
  • Preserves Data Gateway's submitted-without-transaction-hash state for durable pre-broadcast rows.
  • Exposes withdrawal helpers from the Node and browser SDK entry points and keeps server-only direct modules out of browser imports.
  • Uses one canonical escrow balance shape with withdrawingAmount and availableAmount.
  • Keeps paid-read exports from the merged receipt-bound payment work intact.

Validation

  • Focused Vitest passed: 6 files, 150 tests.
  • SDK TypeScript typecheck passed.
  • SDK platform separation, entry-point validation, type declaration generation, and SDK build passed.
  • Packed external consumer validation passed for Node ESM, Node CJS, browser ESM, and TypeScript imports.
  • Targeted ESLint on net-changed TypeScript files passed.
  • git diff --check passed against current origin/main.

Dependency

This SDK surface depends on the matching Data Gateway withdrawal endpoint in data-gateway#67. It is ready for compile-time, mocked, and integration preparation work, but stable release should wait until #67 is merged, deployed, and verified with the live-chain withdrawal test.

Assisted-by: AI

@vercel

vercel Bot commented Aug 11, 2026

Copy link
Copy Markdown

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

3 Skipped Deployments
Project Deployment Actions Updated (UTC)
vana-console Ignored Ignored Aug 17, 2026 11:00pm
vana-rbac-auditor Ignored Ignored Aug 17, 2026 11:00pm
vana-vibes-demo Ignored Ignored Aug 17, 2026 11:00pm

Request Review

@github-actions

Copy link
Copy Markdown
  • P2 – Runtime type guard is unsound (escrow.ts): isEscrowWithdrawalFailureResult accepts arbitrary strings for addresses/txHash and does not validate blockNumber. It then exposes the body as a strongly typed lifecycle result. Validate hex/address fields and optional blockNumber, or loosen the public types to match what is actually checked.

Focused tests could not run because dependencies are not installed (vitest: not found).

@github-actions

Copy link
Copy Markdown
  • Medium — escrow.ts:643: validation remains incomplete. amount, withdrawNonce, deadline, and blockNumber accept arbitrary strings such as "invalid" or "-1", despite representing decimal uint256 values. Validate with a digits-only check plus uint256 bounds before creating a typed lifecycle error.

Tests couldn’t run because pnpm is unavailable.

@github-actions

Copy link
Copy Markdown

No actionable issues found.

Non-blocking: add tests for exact uint256 max and max + 1; the current oversized deadline only exercises the 78-character length guard. Tests couldn’t run locally because dependencies are not installed (vitest: not found).

@github-actions

Copy link
Copy Markdown

No issues found in the incremental change. The tests correctly cover inclusive uint256 maximum acceptance and overflow rejection for all three withdrawal numeric fields.

@tnunamak
tnunamak force-pushed the tim/escrow-withdraw-sdk-0811 branch from 427b72f to 5162bf3 Compare August 13, 2026 22:29
@github-actions

Copy link
Copy Markdown
  • P1 – Withdrawal success type promises fields the gateway may omit. EscrowWithdrawalSettledResult requires deadline via EscrowWithdrawalResponseBase, but the new confirmed-response test omits it. Since withdraw() blindly casts successful JSON, callers can receive undefined where TypeScript guarantees string. Align the type with actual responses and validate successful payloads before returning.

Tests could not run because dependencies/Vitest are not installed.

@github-actions

Copy link
Copy Markdown

No findings in the incremental diff. The new rejection typing and runtime validation are consistent.

Validation note: tests could not run because dependencies are not installed (vitest: not found).

Expose the definite withdrawal rejection error from the public node and browser entrypoints so consumers can handle the SDK error class reliably.

Assisted-by: AI
@github-actions

Copy link
Copy Markdown

No findings in the incremental diff. The error and related types are exported consistently from browser and Node entry points.

Validation note: typecheck couldn’t run because dependencies are incomplete (@types/node missing). git diff --check passed.

Cover the required deadline field in the confirmed withdrawal response fixture and assert that the SDK returns the request deadline unchanged.

Assisted-by: AI
@tnunamak
tnunamak force-pushed the tim/escrow-withdraw-sdk-0811 branch from a42c41a to 7901b94 Compare August 13, 2026 23:24
@github-actions

Copy link
Copy Markdown

No findings. The before and after commits have identical trees, so this push introduces no code changes to review.

Expose the gateway's per-asset withdrawal floor so callers can avoid below-minimum requests without duplicating protocol policy. Preserve null when no floor is configured and cover both balance response paths.\n\nAssisted-by: AI
@github-actions

Copy link
Copy Markdown

No actionable issues found in the incremental diff. The nullable field is consistently added to the public type and both balance response fixtures.

Expose the gateway's chain-scoped nonce snapshot through the escrow client.
Validate account identity and nonce invariants while preserving the existing
optimistic stale-nonce retry contract.

Assisted-by: AI
Git exports repository context to push hooks. Clear it before reading the pinned policy checkout so validation checks the intended repository.\n\nAssisted-by: AI
@github-actions

Copy link
Copy Markdown
  • High – .github/scripts/install-evm-key-scan-hook.sh:50: Unsetting only GIT_DIR and GIT_WORK_TREE does not fully isolate policy validation. A caller-controlled GIT_INDEX_FILE can make git status report a modified policy checkout as clean, allowing an altered hook to execute. Also sanitize repository-affecting variables such as GIT_INDEX_FILE, GIT_COMMON_DIR, and object-directory variables, ideally via a clean allowlisted environment.

The escrow account identifies the debit and payout target. The gateway may also authorize the confirmed owner of a registered app to sign.

Assisted-by: AI
@github-actions

Copy link
Copy Markdown

No findings. The documentation now correctly separates the withdrawal recipient/account from the gateway-authorized signer policy.

@Kahtaf

Kahtaf commented Sep 3, 2026

Copy link
Copy Markdown
Member

FYI: packages/vana-sdk/src/protocol/eip712.test.ts:129 (commit 5162bf3) embeds the Anvil dev key 0x59c6…316c; the org EVM key scan (evm-key-scan.yml, also the pre-push hook) rejects it, so this branch cannot be pushed or pass CI once rebased. A derived scalar, e.g. keccak256(toBytes("vana-sdk-escrow-test")), fixes it.

Kahtaf added a commit that referenced this pull request Sep 9, 2026
Fold SDK PR #186 at d8d6872 while retaining the current scan hook and a derived test fixture key.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants