Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.chipipay.com/llms.txt

Use this file to discover all available pages before exploring further.

Available without advertisement until external audit closes. The on-chain threshold logic shipped with V8.4 (class hash 0x075dfb39…fa58a) and has a mainnet smoke (task #46).

​
When to use threshold

Three concrete use cases:
  1. Vela autonomous agent treasury — a Vela agent spends up to $X/day on its own, anything bigger requires a co-sign from the user’s passkey. The wallet is 2-of-2 (agent owner + user passkey owner) above the spend threshold, 1-of-2 below.
  2. AI-API service-account wallets — a service-account-rooted Starknet wallet (JWT_ES256 owner) shares custody with a human operator (passkey owner). Routine API spend doesn’t prompt; settlement transfers do.
  3. Co-signed gift-card treasuries — an org’s Chipi credits balance is N-of-M with key roles distributed across finance + ops + the founder.

​
Compared to single-owner

Single-owner SHHH wallets sign via one V2_SNIP12 envelope: 
[V2_SNIP12_PREFIX, owner_id, kind_tag, ...payload]
A threshold wallet signs via a threshold envelope wrapping N inner envelopes: 
[
  V2_THRESHOLD_PREFIX,
  threshold,        // N
  num_owner_sigs,   // count of inner envelopes that follow
  ...inner_envelope_1,
  ...inner_envelope_2,
  ...
]
Each inner envelope can be a different signer kind. The wallet validates each inner envelope against its registered verifier class, counts the verified ones, and admits the call only when verified_count ≥ threshold. The set of owners and the threshold N live on-chain.

​
Owner kinds within a threshold

Anything that works as a single-owner signer kind works as a threshold owner. You can mix:
  • An EOA on MetaMask (EIP191_SECP256K1) co-signs with a passkey (WEBAUTHN_P256)
  • A JWT_ES256 service account co-signs with a STARK key held server-side
  • A guardian (role: "GUARDIAN") does NOT count toward the threshold for normal transactions — guardians only initiate recovery, never co-sign

​
Configuring N and M

The wallet is created with N initial owners (M=N at start). Add or remove owners post-creation via the recovery flows in recovery:
  • propose_add_owner → execute_add_owner after 48h
  • propose_remove_owner → execute_remove_owner after 24h
  • propose_set_threshold → execute_set_threshold after 48h
Threshold changes are timelocked because they’re governance-grade — a malicious add-owner that immediately set threshold=1 would be a wallet takeover. The 48h window gives the other owners a chance to cancel_pending_op.

​
SDK status

SurfaceStatusNotes
Backend builders (buildThresholdEnvelope, buildProposeSetThresholdCall, buildExecuteSetThresholdCall)ShippedSee @chipi-stack/backend exports
Python buildersShippedMirrors TS — see chipi_sdk.shhh.threshold
React hookuseGuardianRecovery().buildProposeSetThreshold / .buildExecuteSetThreshold cover the governance sideThe N-of-M signature assembly hook (useThresholdSign) ships next
Mainnet smokeShipped (view-shape + parser)Real-money smoke deferred until external audit closes
import {
  buildThresholdEnvelope,
  buildStarkEnvelope,
  buildEip191EnvelopeFromSignature,
} from "@chipi-stack/backend";

// Two owners co-sign the same OE.
const innerStark = buildStarkEnvelope({ privateKey: serverStarkKey, messageHash: oeHash });
const innerEip191 = buildEip191EnvelopeFromSignature({
  signatureHex: metaMaskPersonalSig,
  pubkey: { ethAddress: userMetaMaskAddress },
});

const envelope = buildThresholdEnvelope({
  threshold: 2,
  innerEnvelopes: [innerStark, innerEip191],
});
// Feed `envelope` into the same execute_from_outside_v2 calldata path
// you'd use for a single-owner OE.

​
Gas

The paymaster sums the per-kind gas overhead across each inner envelope. A 2-of-2 STARK + EIP-191 OE budgets 2M + 10M = 12M l2_gas for verification on top of the call’s own cost. See signer kinds for per-kind numbers. This composes — you don’t budget gas yourself. The paymaster reserves it automatically based on the envelope shape.

​
Threshold + recovery together

The headline product story for SHHH V8.4 is threshold combined with guardian recovery:
  • Day-to-day operations require N-of-M signatures
  • Lost-key recovery still works because a guardian can initiate initiate_recovery even if N-1 owners have lost their keys
A 2-of-3 wallet with one guardian = three signers required day-to-day; one guardian can recover the wallet to fresh owners if two are lost. This is the closest thing to “bank-grade custody without giving up custody” on Starknet today.

​
Related