sip-protocol / sip-protocol/sipher

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

Open
#282 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
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:

  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

  • 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.