sip-protocol / sip-protocol/sipher
feat(sdk): add buildClaimTx + broadcastClaimTx split for SignTxCard claim UX (Spec 4 Path B)
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
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:
- Call `buildClaimStealthPaymentTx` → get `serializedTx`
- Return `status: 'awaiting_signature'` + `serializedTx` to the tool-signing wrapper
- SignTxCard appears in chat → user signs as fee payer
- POST `/api/tool-signing/:flagId/confirm` triggers `broadcastClaimStealthPaymentTx`
- 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
- Spec: `docs/superpowers/specs/2026-05-15-claim-phase-2-design.md` (Path B section, lines ~357-376)
- Path A predecessor: #281
- SDK source: `~/local-dev/sip-protocol/packages/sdk/src/chains/solana/` (the `claimStealthPayment` definition)
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)
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the Path B section in docs/superpowers/specs/2026-05-15-claim-phase-2-design.md and the claimStealthPayment definition under packages/sdk/src/chains/solana/. Then trace packages/agent/src/tools/claim.ts and the /api/tool-signing/:flagId/confirm flow. Done means the SDK exports the split primitives without breaking the wrapper, executeClaim emits tool_signing_required, the frontend SignTxCard handles the two-signer flow, and attribution still uses the claim transaction signature.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, frontend, full-stack
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100