@chipi-stack/backend 14.15.1 → 14.17.0

package/README.md

@@ -93,6 +93,54 @@ A quorum can only **raise** `requiredApprovals` above the wallet's on-chain
 threshold. The chain is the hard floor, so a quorum below it produces proposals
 that reach approved and then revert at execute.
 
+## Bramble and other Starknet wallets
+
+Users who already have Bramble, Braavos or Ready can use it with Chipi. Their key never leaves that wallet.
+
+**Sign in with Starknet** (14.16.0+): Bramble signs a SNIP-12 message with a one-time nonce, and the account checks it.
+
+```ts
+import { createStarknetSignInTypedData, verifyStarknetSignIn } from "@chipi-stack/backend";
+import { RpcProvider } from "starknet";
+
+const now = Math.floor(Date.now() / 1000);
+const typedData = createStarknetSignInTypedData({
+  domain: "app.example.com",
+  uri: "https://app.example.com",
+  address: brambleAddress, // from wallet_requestAccounts
+  nonce,
+  issuedAt: now,
+  expirationTime: now + 600,
+});
+// The browser asks Bramble: wallet_signTypedData(typedData) → signature
+const result = await verifyStarknetSignIn({
+  typedData,
+  signature,
+  provider: new RpcProvider({ nodeUrl }),
+  expected: { domain: "app.example.com", uri: "https://app.example.com", nonce },
+});
+if (result.ok) console.log("signed in as", result.address);
+```
+
+**Trusted wallets** (14.17.0+): Bramble can be a co-owner or a recovery guardian of a Chipi wallet, through the `STARK_SNIP12` signer kind. Once added as a co-owner, Bramble approves transactions with `wallet_signTypedData` and Chipi relays them gaslessly:
+
+```ts
+const txHash = await sdk.executeWithExternalSigner({
+  params: {
+    walletAddress: chipiWallet.publicKey,
+    ownerIndex: brambleOwnerId,
+    calls,
+    signTypedData: async (typedData) =>
+      (await bramble.request({ type: "wallet_signTypedData", params: typedData })) as string[],
+    // Checked off-chain before relaying (key from resolveStarkSnip12Signer).
+    signer: { address: brambleAddress, starkPubkey },
+  },
+  bearerToken,
+});
+```
+
+The `STARK_SNIP12` verifier class is declared on mainnet; `isShhhVerifierDeclared` checks it on any network. Guides: [Sign in with Starknet](https://docs.chipipay.com/sdk/guides/sign-in-with-starknet) and [Trusted wallets](https://docs.chipipay.com/sdk/guides/trusted-wallets).
+
 ## What you can ship
 
 - **Wallet-as-a-service APIs** — provision and manage wallets for your users from your backend