Skip to content

feat(sdk): add buildClaimTx + broadcastClaimTx split for SignTxCard claim UX (Spec 4 Path B) #282

@rz1989s

Description

@rz1989s

Background

Spec 4 Path A shipped in #281 — claim now works end-to-end with honest Torque attribution, but the user has no SignTxCard moment (the chat tool invocation is the consent). Path B was deferred as a post-judges follow-up per the amendment in docs/superpowers/specs/2026-05-15-claim-phase-2-design.md.

What to do

Extend @sip-protocol/sdk (in ~/local-dev/sip-protocol/packages/sdk) with two new exported primitives:

```ts
export async function buildClaimStealthPaymentTx(params: Omit<SolanaClaimParams, 'connection'> & { connection: Connection }):
Promise<{ serializedTx: string; stealthAddress: string; mint: string }>

export async function broadcastClaimStealthPaymentTx(connection: Connection, signedTxBase64: string):
Promise<{ txSignature: string; destinationAddress: string; amount: bigint; explorerUrl: string }>
```

Keep the existing atomic `claimStealthPayment(...)` as a convenience wrapper that calls build then broadcast internally. Strict API superset — no breaking change for any current consumer.

Then in sipher's `packages/agent/src/tools/claim.ts`, change `executeClaim` to:

  1. Call `buildClaimStealthPaymentTx` → get `serializedTx`
  2. Return `status: 'awaiting_signature'` + `serializedTx` to the tool-signing wrapper
  3. SignTxCard appears in chat → user signs as fee payer
  4. POST `/api/tool-signing/:flagId/confirm` triggers `broadcastClaimStealthPaymentTx`
  5. Return `status: 'confirmed'` + claim tx sig

Why

  • UX symmetry with send/swap (consent ceremony via SignTxCard)
  • Better SDK API design — splittable build/broadcast benefits CLI, web app, future integrations
  • Acknowledges the privacy-aware framing that visible tx confirmation is valuable UX even if not cryptographically gating

Cost

  • 4-6 days (SDK PR + npm publish + sipher consumer PR + frontend SignTxCard tweak for claim's two-signer flow)
  • Coordination across `sip-protocol/sip-protocol` (SDK) and `sip-protocol/sipher` (consumer)

References

Acceptance

  • SDK exports `buildClaimStealthPaymentTx` + `broadcastClaimStealthPaymentTx` as separate primitives
  • Existing `claimStealthPayment` still works (no breaking change)
  • sipher `executeClaim` uses the split API, emits `tool_signing_required` SSE
  • Frontend SignTxCard handles claim's two-signer flow (stealth keypair server-side, fee payer client-side)
  • Torque attribution still uses claim-tx-sig (same as Path A — should be free since broadcast returns the sig)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions