Threshold (M-of-N)
The number of stamps any single payout needs to reach quorum and broadcast. Set per customer at claim time assigningThreshold. A 5-member roster with signingThreshold: 2 collects 2 stamps and proceeds; a 3-member roster with signingThreshold: 3 requires all three.
The threshold can be adjusted later via the signing-quorum endpoints. Per-wallet overrides are allowed, with one constraint (see Per-wallet overrides below).
Constraints:
- Threshold must be between
1and the number ofACTIVEsigners. - Raising the threshold above the active signer count returns
422 THRESHOLD_EXCEEDS_ROSTER(at claim time) or422 QUORUM_THRESHOLD_EXCEEDS_SIGNERS(on a quorum update). - Lowering the threshold below
1is rejected at the DTO layer.
Minimum admins
The floor on how manyadmin signers must remain at all times. Admins are the only role that can change the roster (add, remove, promote, demote). The floor is enforced on every roster mutation and on every demote: an attempt that would drop the admin count below the floor returns 403 WOULD_BREAK_MIN_ADMINS (or 422 ROSTER_BELOW_MIN_ADMINS at claim time).
The current floor is 2 admins. The reason is recoverability: with a single admin, losing access to that admin’s passkey would lock you out of the roster permanently. Two admins means either one can promote a fresh admin if the other is compromised or unavailable.
Demoting an admin always triggers a root-quorum ceremony, even when the floor would still be satisfied. Removing an admin directly is rejected with 409 SIGNER_IS_ROOT_MEMBER: you must demote first, then remove.
How the two constraints compose
| Scenario | Threshold check | Min-admin check | Outcome |
|---|---|---|---|
| Claim with 3 signers, threshold 2, 2 admins | Pass (2 ≤ 3) | Pass (2 ≥ 2) | Accepted |
| Claim with 3 signers, threshold 2, 1 admin | Pass | Fail | 422 ROSTER_BELOW_MIN_ADMINS |
| Claim with 3 signers, threshold 4, 2 admins | Fail | Pass | 422 THRESHOLD_EXCEEDS_ROSTER |
| Remove signer when 2 admins, 3 total, threshold 2 | n/a | Pass (2 admins remain if target is a signer) | Accepted |
| Remove admin when 2 admins, threshold 2 | n/a | Block (direct remove on admin) | 409 SIGNER_IS_ROOT_MEMBER (demote first) |
| Demote admin when 2 admins | n/a | Fail (would drop to 1) | 403 WOULD_BREAK_MIN_ADMINS |
| Demote admin when 3 admins, threshold 2 | n/a | Pass (2 admins remain) | Accepted, triggers ceremony |
Per-wallet overrides
A customer can set a different threshold on a specific wallet. Use this when one wallet holds higher-value assets that should require more signatures than the customer default. One-way constraint: a per-wallet override may only lower the threshold relative to the customer default. Raising via override returns422 QUORUM_WALLET_OVERRIDE_CANNOT_RAISE. The reason is policy composition at the signing layer: the customer-default and per-wallet policies are evaluated in parallel, and the effective threshold is the lower of the two. A raise-above-default override would be silently under-enforced because the default still passes at the lower count.
This constraint goes away once the customer-default policy is rewritten to exclude override wallets. Until then, design your override scheme around the one-way rule.
Common pitfalls
- Threshold of 1 on a multi-signer claim. This is allowed, and it collapses the multi-signer surface back to “any one signer can release.” Useful for testing; not what most teams want in production.
- Demoting the second-to-last admin. Hits
403 WOULD_BREAK_MIN_ADMINS. Promote a signer to admin first. - Removing an admin without demoting. Hits
409 SIGNER_IS_ROOT_MEMBER. Demote, wait for the ceremony to complete, then remove. - Sequential roster changes. Promote/demote/add/remove all go through ceremonies, and ceremonies run sequentially per customer. A second mutation while the first is still in flight returns
409 CEREMONY_IN_FLIGHT. Retry with a short backoff.