Skip to content
Pybara Docs

Architecture

How a donation travels from the donor’s wallet to yours.

A donation, step by step

Section titled “A donation, step by step”

  1. The widget

    Before showing anything, the widget asks Pybara whether your site has accepted its terms, in Pybara Wallet, and whether it is switched on. If not, it stays hidden, and the browser’s console says why. Then the donor picks an amount, or enters their own, and whether to give once or on a recurring basis.

  2. The checkout frame

    Pybara Wallet’s checkout opens in a frame on your page. Before showing any amount, it checks that your site’s _pybara-payto DNS record lists your wallet, and that the donation is for the page’s own address.

  3. Wallet and token

    The donor connects Pybara Wallet or OISY, and picks a token: ckUSDC, ckUSDT, ckBTC, ckETH or ICP. The amount is converted at the current rate.

  4. The donation

    The donor’s wallet sends the tokens to the settle canister, into a deposit account derived from your account and a random value made for this donation: the deposit can only ever be paid to you, and only once.

  5. The split

    Settle checks the deposit on the token’s ledger, then splits it: Pybara’s fee, out of which the network fees are paid, and the rest to your wallet. It then records the donation in Pybara’s logs.

  6. Thank you

    The donor sees your thank-you message, or is sent to your thank-you page.

Recurring donations work the same way, except that the donor approves an allowance once, and Pybara’s subscription canister, the only one allowed to use it, pulls each donation through settle when it falls due.

Overview

Section titled “Overview”
Donor's wallet ──► Settle canister ──► Your wallet
                        │
                        ▼
                   Pybara's logs

Guarantees

Section titled “Guarantees”
  • Paid to the wallet your DNS lists: the checkout refuses any other, whatever the page or the script does.
  • Bound deposits: a deposit is tied to your account and to one donation, so it can be neither redirected nor settled twice.
  • An immutable split: the settle canister is blackholed, so no one, not even Pybara, can change its code, and it refuses any fee outside 1–3%.