Developers · BRC-100
BRC-100 PeerPay
SpiffyVault speaks PeerPay, the wallet-to-wallet payment of BRC-100 wallets such as BSV Desktop and BSV Browser. A web wallet, an Electron wallet or a service that uses the BSV SDK can pay a SpiffyVault user, and get paid by one, with the standard @bsv/message-box-client package.
How it works
- The payer makes a transaction to a key derived from the payee's payment key (BRC-29), and sends it as Atomic BEEF, with proof.
- The payment goes into the payee's
payment_inboxon a message box server, encrypted to the payee (BRC-2). The payer signs in to the server with BRC-103. - The payee's wallet collects it when it next runs, checks the proof, and takes the coins.
The payment waits in the message box, so the payee does not have to be online. PeerPayClient does all of this for you.
The payment key
The payment key is a compressed secp256k1 public key: 66 hex characters, starting with 02 or 03. A SpiffyVault user shares it from Get paid, with Who will scan it? › Other BRC-100 wallet and Share key. It is also the k value of their payment link.
- On mainnet, the key is bare:
02…. - On testnet, SpiffyVault shares it as
testnet:02…(and on regtest asregtest:02…), so a mainnet wallet cannot read it and send real coins by mistake. A testnet wallet removes the prefix before it pays. Never remove it in a mainnet wallet.
The payment key is not the user's sign-in identity. Sign-in gives you an Ed25519 key; PeerPay uses this secp256k1 key. Nothing in SpiffyVault links the two for you.
The message box host
SpiffyVault sends and collects PeerPay payments at the public message box server that the BSV Association runs:
https://messagebox.bsvblockchain.tech
- A user can choose another host under Settings › Advanced › BRC-100 message box. Then SpiffyVault uses that host, and reads the old one for 30 more days.
- Set
messageBoxHostinPeerPayClientto this server, so that your payments arrive where SpiffyVault collects them. - SpiffyVault leaves a payment on its own host, not on the host the payee advertises. To get paid by SpiffyVault users, read your inbox at
messagebox.bsvblockchain.tech.
Pay a SpiffyVault user
import { WalletClient } from '@bsv/sdk';
import { PeerPayClient } from '@bsv/message-box-client';
const peerPay = new PeerPayClient({
walletClient: new WalletClient(),
messageBoxHost: 'https://messagebox.bsvblockchain.tech',
});
// The key the payee shared. On testnet: 'testnet:02…' without 'testnet:'.
const recipient = '02…';
await peerPay.sendPayment({ recipient, amount: 25000 }); // satoshis
The SpiffyVault user sees the payment when the app next collects from the message box: when it starts, and about every 30 seconds while it runs.
Get paid by SpiffyVault
Give the SpiffyVault user your wallet's identity key: they scan it as a QR code, or paste it under Scan › Paste a code or key. SpiffyVault pays it over PeerPay. Then collect the payment:
const incoming = await peerPay.listIncomingPayments();
for (const payment of incoming) {
await peerPay.acceptPayment(payment);
}
On testnet, give your key as testnet:02…. A SpiffyVault on testnet refuses a bare key, because a bare key is a mainnet key.
The paying SpiffyVault signs in to the message box with its own BRC-100 payment key. Without one it says that no BRC-100 identity was found. The user sets it up from their avatar, under Identity & keys › BRC-100 payment key › Set up.
Without a BRC-100 wallet
A page or a service with only a private key can collect PeerPay payments too. acceptPeerPayPayments in @spiffyvault/payments reads the inbox as SpiffyVault does:
import { ProtoWallet, PrivateKey } from '@bsv/sdk';
import { acceptPeerPayPayments } from '@spiffyvault/payments';
const payee = await acceptPeerPayPayments({
network: 'testnet',
wallet: new ProtoWallet(PrivateKey.fromHex(keyHex)), // its identity key is your payment key
onPayment: async p => keep(p), // checked and on the network: keep p.atomicBeef and p.outputs
});
- Every 10 seconds it lists
payment_inboxon BSVA's message box (passhostfor another).ProtoWalletis enough to sign in to the server and to open the messages. - For each token it checks that the output pays your BRC-29 key (protocol
[2, '3241645161d8'], key IDderivationPrefix + ' ' + derivationSuffix, counterparty the sender's identity key) exactly the amount the token says, checks the transaction by SPV, and sends it to the network once more to learn that the network has it. - It acknowledges a message, which deletes it from the server, only after
onPaymentreturns. WhenonPaymentthrows, the payment is offered again on the next pass. Keep payments by txid: after a restart the same one can come again. - To keep a coin, you need its key: derive it from the same values with your private key, or take
p.outputsinto a BRC-100 wallet withinternalizeAction.
To read the inbox yourself instead, use MessageBoxClient from @bsv/message-box-client with a ProtoWallet. Use listMessagesLite and pass the host on every call: listMessages tries to take the payment into a full BRC-100 wallet, which a ProtoWallet is not.
Limits
- PeerPay has no way to refuse a payment. To give money back, pay it back.
- SpiffyVault reads the payment output at index 0 of the transaction, as
PeerPayClientmakes it. - The message box server limits the size of a message. A payment that spends many small coins can be too large: join the coins first.
- A message box keeps a message for a limited time. Collect payments at least every few days.