Shared wallet
Money more than one person controls: how the approval rule is enforced by the script rather than by policy, and what that costs.
A wallet two or more people control together: a household fund, a small business account, a club's money, a project's budget.
The reason to build it on multi-key rather than on an admin setting is that the rule becomes part of the money. "Two of us must approve" written into the output is enforced by the network; the same rule written into your database is enforced by your company continuing to exist and behave.
Who it is for
Three shapes, with quite different needs:
| Household | Small business | Group or club | |
|---|---|---|---|
| Members | 2, high trust | 2 to 5, working trust | Many, low trust |
| Typical rule | Either can spend, both can see | Two of three directors | A treasurer who must be countersigned |
| What matters most | Not getting in the way | An audit trail | Nobody can act alone |
Do
Ask what the group is protecting against before offering a rule. "One of us loses a phone" and "one of us might take the money" need different answers, and only the second needs a threshold above one.
Setting it up
Each member creates their own key on their own device. Nobody's key ever leaves their device, and nobody holds anybody else's.
Do
Let an unfinished setup be saved and resumed. Getting three people to be available at once is the step most likely to stall.
Do
Show whose key is set up and whose is outstanding, and give a way to nudge the people who are missing.
The recovery key
A shared wallet needs an answer to "one of us is unreachable", and a threshold alone does not give one: if two of three must sign and one person vanishes, the remaining two can still spend, but if two vanish the money is stuck.
Do
Include a recovery key held outside the group, or by the group's least active member, and say plainly what it can and cannot do on its own.
Don't
Let a recovery key spend alone. It should be one of a quorum, not a back door, or the arrangement is not shared control.
Adding a recovery key to two of three makes it two of four: the recovery key plus any one member can spend. Say that when you ask who should hold it.
On BSV specifically
Three things are particular to a BSV shared wallet, and all three reach the interface.
The arrangement is public, if it is built as a multi-key script, which shared control needs so that nobody's key is ever rebuilt in one place. New pay-to-script-hash outputs are not allowed, so the keys and the threshold are visible in the output from the moment it exists. Anyone can see that this is a two-of-three. Design on the assumption that the rule is readable, and never rely on it being secret. See Multi-key.
The configuration is a backup item. A quorum of signers who have lost the record of which keys and what threshold cannot construct a valid spend. It needs backing up with the same care as a key, and it is privacy-sensitive because it maps the whole group.
Payments still arrive peer to peer. The wallet that receives is one wallet, with one handle, even though several people control it. Incoming payments do not need a quorum. See Payments.
Day to day
The interesting state is "waiting", which an ordinary wallet does not have.
Do
Show who has signed, who has not, and how long it has been waiting. Most of the time a shared payment is blocked on a person, not on the network.
Do
Notify the people whose signature is outstanding, and let anyone in the group nudge them without leaving the app.
Do
Let a proposer cancel their own pending payment cleanly, without leaving funds reserved.
Don't
Show a pending shared payment as "Sending". Nothing has been sent, and the difference matters when somebody is waiting to be paid.
Say who did what
A shared wallet's activity list is a record several people rely on.
Do
Attribute every payment to the member who proposed it and the members who approved it, and keep the note field prominent. "Who bought this and why" is the question a shared account gets asked most.
Leaving and changing the group
The part most shared wallets never build, and the part every group eventually needs.
Changing who can sign, or replacing any member's key, means changing the spending condition, which means moving the money to a new arrangement. It is not an edit.
Do
Design it as a migration with a clear explanation: a new wallet is created with the new members, and the balance is moved to it in a payment the current quorum approves.
Do
Keep the old wallet's history visible after the move. The money changed arrangement; the record of what the group spent did not.
Don't
Imply a member can be removed without the remaining members acting. Anybody holding a key keeps it, and the only remedy is to move the funds somewhere their key does not work.
Open questions
- Do households want every payment approved, or a limit below which either partner spends alone? That limit would be the policy of an auto-signing key, as in the savings wallet, not a rule in the script.
- Who do groups trust with a recovery key: an outsider, a service, or a member?
- What does a member who has left expect to keep seeing of the history?
Pros and cons
Pros
- No single person can move the money, and no single loss strands it.
- The rule is enforced by the script rather than by a policy or a company.
- Every payment has an attributable proposer and approvers.
Cons
- Setup needs several people in several places, which makes it easy to abandon.
- Every payment takes more than one action, so it is wrong for daily spending.
- The arrangement is public on BSV, including the threshold.
- Changing the membership means moving the money, not editing a list.
Related
Written from: BRC-29, BRC-42, BRC-52, ts-stack script docs.
Checklist
The rules on this page, in a form you can work through.
13 rules