[daniil-dovgal]

Description

High level implementation overview

First milestone of the TS SDK quorum stack, stacked on #2268. The foundation: #2214 reads quorum entries, #2215 adds the rules and errors, #2233 the signer seams, #2225 approval collection and the quorum-only poll outcome, and #2268 makes a quorum signer return { transactionId } unsigned.

This PR lets a client approve as a quorum member on EVM and Stellar, per EDD 007 §7 "Approval" and "Role" (crossbit-main #33357, merged):

• approve signs every pending member this client holds, each over its own message: transactions on both chains, signatures (ERC-1271) on EVM.
• While other members must still sign, approve returns the request without hash (or signature) instead of throwing.
• useSigner accepts a key that is only a quorum member.

Before, any quorum entry threw QuorumSignerNotSupportedError, and useSigner refused member keys. Wallets without quorums behave as before. Solana keeps the guard: it has no quorums.

await wallet.useSigner(bob); // Bob is only a member of `treasury`
const tx = await wallet.approve({ transactionId });
if (tx.hash == null) {
    // other members must still sign
} else {
    showReceipt(tx.hash); // Bob's approval completed the quorum
}

Details

• wallets/wallet.ts approval paths: when a quorum entry is pending, the held keys come from heldSigners() (feat(wallets): acting-signer seam, held signers and quorum API errors at call sites (quorum foundation 3/4) #2233), and every held pending member signs (§7 "never counts the threshold"; the API skips extras). If nothing held is pending, no request is sent. An api-key wallet leaves its flat entries to the API, as today.
• chains/adapters/stellar.ts: supportsQuorumApprovals is on. The API sends one quorum entry per auth entry, so a member signs once per entry, all in one request; the API rejects only a member shared by two different quorums. A passkey member signs the hex of the 32-byte message, one prompt after another.
• wallets/services/operation-poller.ts: a quorum-only wait returns { transactionId } with hash / explorerLink undefined, or { signatureId } with signature undefined. The types stay Transaction<false> / Signature<false> (EDD "Type honesty"), so callers check hash == null. A wait on any other signer still throws TransactionAwaitingApprovalError. No quorum progress is built any more, so an unreadable entry can't throw a plain Error (audit finding 11). SignatureAwaitingApprovalError, the error's quorums and QuorumApprovalProgress are gone; none was released.
• Callers that act on the wait's result: addSigner resuming a registration that quorum members must still approve returns the signer with its transactionId / signatureId and its own status, as prepareOnly does. Stellar upgrade() returns phase 1 without a hash and creates no migrate transaction, since the wallet is not locked yet.
• useSigner member keys (wallet.ts, signers/server/resolver.ts): a key resolves as a registered signer, then a recovery method, then a quorum member. A member takes its quorum's status, without the getSigner lookup that 404s for members. A passkey member needs its id.
• api/client.ts approveTransaction: when two members race for the last slot, the API answers 422 "Already has the required number of approvals"; the client re-reads the transaction and goes on to its outcome. Every other 422 is returned unchanged.

Next Steps

E2 (#2256): a member-only active signer acts as its quorum and returns early, and EVM signMessage / signTypedData take signer. E3 (#2261): signer changes approved by a quorum.

Accepted:

• removeSigner, the recovery-method calls and device recovery still treat any return of the wait as landed. They approve with a flat recovery signer here, so they can't reach a quorum-only wait; E3 and E5 keep that true.
• Stellar upgrade / migrate with a quorum signer sign held members (feat(wallets): a quorum acting signer returns the created transaction unsigned, as prepareOnly does (quorum foundation 5/5) #2268 left them out, as the EDD does). Unreachable: quorum proofs need a v2 contract, and v2 has no upgrade target.
• A Solana api-key wallet with a quorum-only wait returns without a hash, like the other chains; the API rejects Solana quorums.
• A passkey member whose wallet has an id-less passkey recovery method resolves as that recovery method. A key in two delegated quorums takes the first one's status.

Test plan

• Tests first. The Stellar and approve-rule commit's red baseline: 23 failed, 122 passed (the guard, the old awaiting errors, quorums on the outcome).
• Suites:
  • wallet.quorum-approve.test.ts: the rules above on transactions and signatures, api-key wallets, addSigner resume, and a Stellar block (two auth entries, passkey and email members, others pending, expiry on submit and while waiting, the last-slot race, a flat entry not held).
  • wallet.quorum-member-signer.test.ts: every member type in recovery and delegated quorums.
  • operation-poller.test.ts (incl. finding 11), stellar.test.ts (upgrade / migrate), chain-adapter.test.ts, resolver.test.ts, and api/client.test.ts (422 rows; CI only, needs PREVIEW_CK_KEY).
• Run: cd packages/wallets && pnpm exec vitest run src/wallets src/quorum src/utils src/chains src/signers → 1139 passed. tsc on src/ is clean; biome reports no errors.
• Fresh-context review: three rounds for the EVM part, two for the Stellar part (Ready). The addSigner and Solana rows are mutation-checked.
• Not here: a live Stellar testnet run (E6).

Package updates

• @crossmint/wallets-sdk: minor (.changeset/quorum-approve-as-member.md).

[changeset-bot]

🦋 Changeset detected

Latest commit: 2511db4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@crossmint/wallets-sdk	Minor
@crossmint/wallets-quickstart-devkit	Patch
@crossmint/wallets-playground-react	Patch
@crossmint/client-sdk-react-base	Patch
@crossmint/client-sdk-react-native-ui	Patch
@crossmint/client-sdk-react-ui	Patch
@crossmint/integration-tests	Patch
@crossmint/wallets-playground-expo	Patch
@crossmint/auth-ssr-nextjs-demo	Patch
@crossmint/client-sdk-nextjs-starter	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[greptile-apps]

Confidence Score: 5/5

[Critical impact] The PR appears safe to merge.

_{Reviews (1) · Last reviewed commit: "fix(wallets): export TransactionAwaiting..." · Reviewed by Greptile}