---
title: GoodStream — Technical Specification
description: End-to-end spec for GoodStream (goodstream.in), a Genji-based, non-custodial app where senders pay by card through the Stripe crypto onramp (with a MiCA-licensed partner CASP as the near-zero-fee, automatic monthly target), month by month above €10 or as an upfront budget below, or use ETH they already own, and pledge a monthly amount on Ethereum mainnet from their w3pk passkey account, and creators opt in, by registering themselves or by logging in with YouTube, Twitch, Instagram or email, then collect it whenever they like with gas paid by GoodStream, with a single escrow contract, hosted on an Infomaniak VPS with SQLite and designed for GDPR compliance.
date: 2026-11-20
lang: en-US
author: Julien Béranger
model: Claude Opus 5.5
conversation: https://claude.ai/chat/4dd51741-2618-44e3-a98e-beaa4348d080
source: https://julienberanger.com/goodstream-spec
---

# GoodStream — Technical Specification

> **TL;DR** Anyone can start a monthly stream of money to the content creator of their choice, with just a passkey and either a card or ETH they already own. Card streams above €10 a month are paid month by month; smaller ones are paid upfront as a budget, to keep Stripe fees low. The creator opts in by registering or simply by logging in with YouTube, Twitch, Instagram or email, and collects whenever they want. The sender can take back whatever hasn't been streamed yet, at any time. v1 buys ETH through Stripe's onramp; the target is a partnership with a MiCA-licensed seller, so that a payment costs little more than the card or bank fee and monthly payments run on their own (§10.8). GoodStream lives at [goodstream.in](https://goodstream.in).

## 1. Summary

GoodStream lets anyone support independent media and creators with a monthly ETH contribution:

1. **Account.** A sender signs in with a [w3pk](https://github.com/w3hc/w3pk) passkey. Their w3pk **primary account** is their wallet.
2. **Fund.** The sender puts ETH in that account in one of two ways:
   - **Pay by card.** They buy ETH through the [Stripe crypto onramp](https://docs.stripe.com/crypto/onramp), embedded in the app (card, Apple Pay or Google Pay). Stripe sells the ETH and delivers it straight to the sender's primary account.
   - **Use ETH they already own.** They send ETH from any wallet or exchange to their primary account's address. No Stripe, no KYC, no onramp fee.

   **GoodStream never sells or holds ETH, and can't move it anywhere except to the chosen recipient, on the sender's schedule.**
3. **Pledge.** From their account, the sender locks ETH in the `GoodStreamEscrow` contract on [Ethereum](https://ethereum.org/) mainnet for a recipient identified by a **YouTube channel, Twitch account, Instagram account or email address**. A stream is paid in one of two ways (§10.2.1):
   - **Monthly payments** (card, more than €10 a month): Stripe charges one month at a time, a few days before it falls due, and each payment funds that month's pledge. Nothing is held in advance beyond the current month.
   - **Budget** (€10 a month or less, or ETH the sender already owns): one upfront payment covers as many months as the budget allows, which spreads fixed fees over several months.

   Every action is a transaction signed by the primary account after a passkey approval. The pledge works the same whichever way the ETH arrived.
4. **Monthly release.** The first monthly amount is due to the recipient as soon as a pledge is funded, then one more every 30 days. The contract computes this from the pledge's start time, so nothing has to be called each month. Funds accumulate whether or not the recipient has opted in yet, and the sender can cancel at any time to take back whatever isn't due yet. The link between a person and their escrow entry lives only off-chain (§11).
5. **Opt in and claim.** Recipients are opt-in. A creator can **register themselves** before anyone pledges, or **opt in by logging in** with YouTube, Twitch or Instagram (or an email magic link) when they come to claim. Either way, proving control of the identity is what opts them in. GoodStream's attester then proposes their wallet as the payout address on-chain, and after a 48-hour challenge window the recipient can collect what's due in ETH whenever they want, with GoodStream paying the gas (§10.4).

### 1.1 Who can do what

| | Options |
| --- | --- |
| **Sender: funding** | **Pay by card** (card, Apple Pay, Google Pay) through the embedded Stripe onramp, month by month above €10 a month or as an upfront budget, or **use ETH they already own**, sent to their GoodStream wallet from any wallet or exchange (§10.1, step 4) |
| **Recipient: opting in** | **Register themselves** on GoodStream, before or after anyone pledges (§10.4.1), or **opt in by logging in** with YouTube, Twitch, Instagram or an email magic link when claiming a pledge (§10.4.2) |

Until a recipient opts in, they're only *designated*: money accumulates for them in the escrow, they get at most one notification, and they can object (§11.4).

## 2. Regulatory position

**Chosen design:** Stripe sells the ETH through its crypto onramp, and GoodStream is non-custodial software.

- **MiCA.** Selling ETH for euros is the service MiCA defines as "exchange of crypto-assets for funds" (Art. 3(1)(19)), which requires CASP authorisation under [MiCA](https://en.wikipedia.org/wiki/Markets_in_Crypto-Assets). With the onramp, Stripe is the seller and merchant of record, and GoodStream sells nothing. Licensed ramps state that integrating them doesn't by itself make the integrating platform a CASP. When the sender uses ETH they already own, no exchange happens at all. Monthly payments keep this split: every month is a separate Stripe onramp purchase confirmed by the sender, and GoodStream never charges a card itself (§10.1.1). The planned partner model keeps it too: a MiCA-authorised CASP sells the ETH, charges the card or SEPA mandate on its own merchant account, and delivers to the escrow on its customer's behalf. GoodStream never receives or forwards euros (§10.8).
- **VAT.** The CJEU's *Hedqvist* ruling (C-264/14, 2015) held that exchanging traditional currency for bitcoin is exempt from VAT under the currency exemption of the VAT Directive; the same reasoning covers Stripe's ETH sale. GoodStream charges no fee (§10.2), so it has no VAT to collect on its service. Its only income is a voluntary "support GoodStream" transfer suggested to creators when they collect (§10.4.3). It buys nothing and changes nothing in the service, so, like the street musician's tips in the CJEU's *Tolsma* ruling (C-16/93, 1994), it should fall outside the scope of VAT; confirm with an accountant (§13). Any real GoodStream fee would be subject to VAT (TVA at 20% for French consumers).
- **Custody.** GoodStream never holds user ETH. Unpledged ETH, whether bought by card or sent in by the sender, sits in the sender's own w3pk account. Pledged ETH sits in a non-upgradeable escrow contract with no admin withdrawal path: it can only go to the verified recipient on the schedule the sender signed, back to the sender when they cancel, or back to senders through a refund (§12.4). Monthly amounts become due on-chain without any transaction, and `payout()` is permissionless, so GoodStream's server is a convenience, not a gatekeeper. Support transfers from creators go to GoodStream's own treasury Safe; they are GoodStream's money, not user funds.
- **Still to confirm with a lawyer (§13):** whether the attester, by deciding which wallet an escrow entry pays, or the relayer, by pushing payouts to recipients, could be seen as providing transfer services on behalf of others.

## 3. Scope

**In scope (v1):** ETH only, Ethereum mainnet only. Passkey accounts (w3pk primary account), two funding paths (card through the embedded Stripe onramp, or ETH the sender already owns), monthly card payments for streams above €10 a month and upfront budgets for the rest (§10.2.1), monthly pledges to four identity types, recipient opt-in (self-registration, or login when claiming) via OAuth or magic link, on-chain payout proposals, payouts with gas paid by GoodStream, withdrawals, a voluntary "support GoodStream" suggestion when creators collect, guardian veto, sender and recipient dashboards, GDPR compliance (§11).

**Out of scope (v1):** GoodStream selling crypto or collecting euros, custody of user funds, GoodStream fees, card onramps other than Stripe (§10.7), automatic monthly charges through Stripe's onramp (§10.1.1), smart-contract accounts for senders, other tokens, other chains, off-ramp to fiat, per-second streaming, renamed Instagram accounts, zkTLS proofs, bio-code verification.

**Ready in v1, switched on once signed:** a partner CASP behind the same onramp interface as Stripe, with automatic monthly payments delivered by `fundFor` (§9.1, §10.8). The contract ships with `fundFor` from day one, so no redeployment is needed.

**Planned after v1:** more recipient identities: X/Twitter, TikTok, Substack, and websites/domains ([ERC-7529](https://eips.ethereum.org/EIPS/eip-7529) or DNSSEC).

## 4. Stack

| Layer | Choice |
| --- | --- |
| Domain | [goodstream.in](https://goodstream.in) (the only domain GoodStream needs) |
| App base | [Genji](https://github.com/w3hc/genji) — [Next.js](https://nextjs.org/), [Chakra UI](https://chakra-ui.com/), [ethers v6](https://docs.ethers.org/v6/), WCAG 2.1 AA, GPL-3.0 |
| Signer and sender wallet | w3pk passkey wallet, **primary account** (shipped with Genji); [SIWE](https://eips.ethereum.org/EIPS/eip-4361) for backend sessions |
| Chain | Ethereum mainnet (chain ID `1`); [Sepolia](https://ethereum.org/en/developers/docs/networks/#sepolia) for testing |
| Token | Native ETH (no wrapping) |
| Escrow | `GoodStreamEscrow`, GoodStream's only contract (§9) |
| Onramp (card path) | [Stripe embedded onramp](https://docs.stripe.com/crypto/onramp/embedded-overview), destination ETH on Ethereum, plus Stripe [webhooks](https://docs.stripe.com/webhooks). ETH on Ethereum is offered to merchants in all Stripe countries and to buyers in the EU and US ([availability](https://docs.stripe.com/stablecoins/availability)). The only onramp at launch (§10.7). A partner CASP plugs in behind the same backend interface (`OnrampProvider`: quote, start purchase, status webhook, and for the partner, subscriptions) (§10.8) |
| Hosting | One [Infomaniak](https://www.infomaniak.com/) Ubuntu VPS in Switzerland (§4.1) |
| Backend | Next.js route handlers, a worker process for jobs and schedules, a relayer for recipient payouts |
| Database | SQLite through [better-sqlite3](https://github.com/WiseLibs/better-sqlite3), one file on the VPS |
| Contracts | Solidity, [Foundry](https://getfoundry.sh/) |

GoodStream deploys a single contract (§9). Senders use their w3pk primary account directly: there is no smart account to deploy.

### 4.1 Runtime

Everything runs on one VPS as long-running processes managed by systemd:

| Process | Role |
| --- | --- |
| Reverse proxy (Caddy or Nginx) | TLS for goodstream.in, forwards to Genji |
| `genji-web` | `next start`: UI, API route handlers, Stripe webhook endpoint |
| `genji-worker` | Same codebase, single instance. Runs the job queue (attester and relayer transactions) and the schedules (§10.6) |

- **Job queue.** A `jobs` table in SQLite. The worker claims a job with `UPDATE … RETURNING` inside `BEGIN IMMEDIATE`. Because there's only one worker, relayer nonces stay in order without extra locking. Web requests and webhooks only insert jobs; they never send transactions themselves.
- **Schedules.** node-cron inside the worker (or systemd timers calling worker commands). Every scheduled job is idempotent, so a missed or repeated run is harmless.
- **SQLite settings.** `journal_mode=WAL`, `busy_timeout=5000`, `foreign_keys=ON`, `secure_delete=ON` (so retention deletions don't linger in free pages). Write transactions stay short; no transaction is held open across an RPC call or while waiting for a receipt.
- **Backups.** [Litestream](https://litestream.io/) replicates the database continuously to off-site object storage (e.g. Infomaniak Swiss Backup), plus a nightly snapshot made with SQLite's online backup API. Backups expire within the retention windows of §11.3, and a restore is tested before launch.
- **Webhooks.** The Stripe endpoint verifies the signature with the Stripe SDK, updates the onramp session's status and returns `200` quickly. The update is idempotent, so retries and duplicate deliveries are harmless. Webhooks only drive the progress display: the pledge is sized from the ETH that actually reaches the sender's account (§10.2), so a missed webhook never blocks anything.
- **Downtime.** If the VPS is down, pledged ETH stays safe in the escrow and nothing is lost. Monthly amounts keep becoming due on-chain regardless. Payout proposals, relayed payouts and monthly payment reminders pause until the VPS is back. In the meantime, anyone can call `payout()`, and recipients can call `withdraw()`, directly.

### 4.2 Secrets

As simple as possible: no external KMS in v1.

- The relayer key, attester key, email pepper and data encryption key live in one root-owned file (`/etc/goodstream/secrets.env`, mode `600`), passed to the services with systemd `LoadCredential` (or `EnvironmentFile`). They are never committed and never logged.
- An encrypted copy (e.g. with [age](https://github.com/FiloSottile/age)) is kept offline by the operators. Losing the pepper makes email lookups impossible, so it must be backed up.
- The relayer and attester wallets only hold a small gas float, topped up manually from GoodStream's treasury Safe (§9.3).
- What limits a stolen attester key: the escrow only accepts proposals from the current attester, the guardian can rotate it, every payout proposal waits 48 h before it takes effect, and proposals are rate-limited with alerts (§12.1).

## 5. Actors

| Actor | Description |
| --- | --- |
| **Sender** | Holds ETH in their w3pk primary account, either **bought by card** through Stripe or **sent in from a wallet or exchange they already use**. Creates and manages streams and pledges, pays their own gas. |
| **Recipient** | Creator or outlet identified by a platform account or email. **Opts in** either by registering on GoodStream or by logging in with the platform (or an email magic link) when claiming (§10.4). Payout goes to their w3pk primary account (or a Safe of theirs). |
| **Stripe** | Onramp provider and merchant of record for the card path. Sells ETH, runs KYC, handles payment, fraud and chargebacks, delivers ETH to the sender's primary account. Not involved when the sender uses ETH they already own. |
| **Attester** | Backend hot key (§4.2) that proposes verified payout wallets to the escrow and pays the gas for those proposals. Rotatable. |
| **Guardian** | 2-of-3 Safe that can veto a payout proposal during its challenge window, rotate the attester and open refunds. |
| **Relayer** | Backend wallet that calls `payout()` and pays its gas, so recipients never need ETH to get paid. GoodStream covers this cost permanently (§9.3). |
| **Partner CASP** (planned) | MiCA-authorised seller of ETH (§10.8). Runs KYC, charges the sender's card or SEPA mandate on its own merchant account, including automatic monthly charges, and delivers ETH to the sender's account or straight into the escrow with `fundFor`. Merchant of record for its sales. |
| **Treasury** | GoodStream's own Safe. Receives voluntary support transfers (§10.4.3) and tops up the relayer and attester gas floats. Holds no user funds. |

## 6. Sender wallet

The sender's wallet is their w3pk primary account, which ships with Genji. There is no separate smart account.

- **Two ways to fund it.** By card: Stripe delivers ETH straight to the primary account's address. With ETH the sender already owns: they send it to that same address from any wallet or exchange, on Ethereum mainnet. The app shows the account as "your GoodStream wallet", with its address and a QR code.
- Every sender action (fund, top up or cancel a pledge, send leftover ETH elsewhere) is an ordinary Ethereum transaction. The sender approves it with their passkey, the primary account signs it, and the app sends it. Gas is paid from the account's own ETH: every purchase or transfer includes a gas reserve for this (§10.2).
- The sender stays in full control: GoodStream can't move their funds. The account is recoverable through w3pk's backup and recovery, and the escrow can be called from any wallet holding the account if GoodStream disappears.

## 7. Recipient identities

### 7.1 Recipient key

Every recipient gets a **random** `recipientKey`, created the first time anyone designates them or the first time they register themselves, and stored off-chain with the identity it stands for:

```text
recipientKey = random 32 bytes (CSPRNG), unique per (platform, canonicalId)
```

The key is never derived from the identity, so nothing on-chain can be traced back to a person without GoodStream's database. Deleting the database row (§11.5) makes the on-chain key meaningless. This follows the EDPB's guidance that personal data shouldn't be stored on a public blockchain and that hashing alone isn't enough.

| `platform` | `canonicalId` (off-chain only) | How the sender designates it | Resolution at pledge time |
| --- | --- | --- | --- |
| `youtube` | Channel ID (`UC…`) | Channel URL or `@handle` | [YouTube Data API](https://developers.google.com/youtube/v3/docs/channels/list) `channels.list` (`forHandle` / `id`) with an API key |
| `twitch` | Numeric user ID | `twitch.tv/<login>` | [Twitch Get Users](https://dev.twitch.tv/docs/api/reference/#get-users) with an app token |
| `instagram` | Lowercased username | `instagram.com/<username>` | No public ID lookup assumed; key on username (see §7.3) |
| `email` | `hex(HMAC-SHA256(pepper, lowercase(email)))` | Email address | None; the raw email is only kept as long as needed to notify (§11.4) |

Use stable platform IDs wherever possible: handles change and can be re-registered by someone else. More platforms (X/Twitter, TikTok, Substack, domains) are planned after v1 (§3).

### 7.2 Sender confirmation

Before a pledge is created, the app shows a preview card (avatar, display name, handle, platform link) and the sender confirms. If the recipient has opted in (§10.4), the card carries an **"On GoodStream"** badge; otherwise it says the creator hasn't joined yet and will be invited to collect. This is the main defence against look-alike accounts. The preview is fetched live from the platform API and not stored beyond the minimal profile in §11.3.

### 7.3 Platform caveats

- **YouTube.** `youtube.readonly` is a sensitive Google scope, so the OAuth app needs Google verification before going public. Channels owned by a Brand Account require the user to pick that account in Google's chooser.
- **Instagram.** The [Instagram API with Instagram Login](https://developers.facebook.com/docs/instagram-platform/instagram-api-with-instagram-login) only serves **professional accounts** (businesses and creators). Personal accounts can't opt in through Instagram in v1 and must use email. Because the key is the username, renamed accounts aren't handled in v1: pledges to the old username follow the normal refund path if they stay unclaimed (§12.4).
- **Email.** The pepper is used only off-chain, for lookups and the suppression list. Keep it in the secrets file and back it up (§4.2).

## 8. Identity proof methods

Recipients sign in with w3pk first (SIWE session), then prove one identity, so the proven identity is bound to the session's wallet. **Proving an identity is what opts a recipient in**, whether they're registering on their own or claiming a pledge (§10.4).

| Method | Protocol | Proof checked by the backend |
| --- | --- | --- |
| **YouTube** | Google OAuth 2.0 (auth code + PKCE), scope `https://www.googleapis.com/auth/youtube.readonly` | `channels.list?part=id&mine=true` returns the channel ID behind the recipient key |
| **Twitch** | [Twitch OAuth](https://dev.twitch.tv/docs/authentication/) (auth code), no extra scope | `GET /helix/users` with the user token returns the user ID behind the recipient key |
| **Instagram** | Instagram Login (auth code) | `GET /me?fields=user_id,username` returns the username behind the recipient key |
| **Email (magic link)** | Single-use link, 15-minute expiry, token stored hashed | Clicking the link proves inbox control; the backend recomputes the HMAC key |

OAuth tokens are used once, in memory, to verify ownership and are never stored; GoodStream doesn't keep platform access.

## 9. Smart contract

GoodStream deploys a single contract, `GoodStreamEscrow`. It holds every pledge and every recipient's allowance: no clones, no per-recipient deployment, no external attestation protocol.

### 9.1 How it works

- **`fund(key, monthly, months)`** locks `monthly × months` wei for a recipient key. The first month is due immediately, then one more every 30 days. A budget stream is one pledge with several months; a monthly-payment stream is a series of one-month pledges, one per payment (§10.1.1). The contract doesn't distinguish them: streams are grouped off-chain (§11.3).
- **`fundFor(sender, key, monthly, months)`** does the same, but the ETH comes from the caller while the pledge belongs to `sender`: only `sender` can top up or cancel it, and refunds go to `sender`. It lets a partner CASP deliver a monthly payment it has just sold straight into the escrow for its customer, with no passkey approval needed (§10.8). The caller gains no rights over the pledge. A `FundedFor` event records the payer for auditing.
- **Nothing runs monthly.** What's due is computed from the pledge's start time (`releasable()`). It's settled into the recipient's allowance whenever the pledge is touched: by `payout`, `withdraw`, `cancel` or `topUp`. Settling late catches up every missed month; nothing can ever be settled early or beyond what the sender locked.
- **`topUp`** adds months to a pledge that still has months to come. **`cancel`** settles what's already due to the recipient, then returns the rest to the sender. Changing the monthly amount of a budget stream means cancelling and funding a new pledge (two passkey approvals).
- **Payout wallet.** After a recorded off-chain verification (§8), the attester calls `proposePayout(key, wallet, method)`. This works whether or not the key has pledges yet, so a self-registered recipient can have a payout wallet in place before anyone pledges. The wallet takes effect after a fixed 48 h challenge window, during which the guardian can `veto` it. No separate finalize transaction is needed: the first `payout` or `withdraw` after the window records it. The `method` code (`1` YouTube, `2` Twitch, `3` Instagram, `4` email) is only emitted in the event, for auditing. Changing a payout wallet is a new proposal; the current wallet stays active until the new one takes effect.
- **`payout(key, pledgeIds)`** is public: anyone can call it. It settles the given pledges and sends the whole allowance to the payout wallet, and nowhere else. GoodStream's relayer uses it so recipients never need ETH.
- **`withdraw(key, to, pledgeIds)`** can only be called by the payout wallet itself. It settles the given pledges and sends the whole allowance to `to`. The recipient pays the gas.
- **Payout addresses** must be able to receive ETH (an EOA or a Safe).
- **Refunds.** For a key that never got a payout wallet, the guardian can `openRefund(key)`. Settlements, proposals and new pledges for that key stop, and `reclaim(pledgeId)` (anyone can trigger it; funds go to the pledge's sender) returns the pledge's full contribution, settled and unsettled (§12.4).
- **Admin.** The guardian can only rotate the attester and the guardian. There is no upgrade path, no adjustable parameter and no admin withdrawal.
- **No fee, no support cut.** The contract takes nothing. The voluntary support transfer (§10.4.3) is a separate transaction from the creator's own wallet, after the payout.
- **Accounting invariant.** The contract's ETH balance equals the sum of unsettled pledge amounts plus the sum of allowances (or exceeds it, if someone force-sends ETH; the contract has no `receive()`).
- **Privacy.** On-chain, a recipient is only a random 32-byte key (§7.1). No identity, handle, email or hash of one is ever written.

### 9.2 Code

Solidity `^0.8.24`, depends only on OpenZeppelin's `ReentrancyGuard`. Every ETH transfer follows checks-effects-interactions behind `nonReentrant`.

```solidity
// SPDX-License-Identifier: GPL-3.0
pragma solidity ^0.8.24;

import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

/// @title GoodStreamEscrow
/// @notice Holds monthly ETH pledges for recipients identified only by a random
///         off-chain key. A pledge's first monthly amount is due at funding, then
///         one more every PERIOD: nothing has to be called each month. Once a
///         payout wallet is set (attester proposal + challenge window), anyone can
///         push what is due to that wallet (payout), and the wallet itself can
///         pull it to any address (withdraw).
/// @dev    Non-upgradeable, no admin withdrawal path. ETH only ever leaves to a
///         recipient (payout, withdraw) or to a pledge's sender (cancel, reclaim).
///         Invariant: address(this).balance >= sum of unsettled pledge amounts
///         + sum of allowances (">=" only because ETH can be force-sent; the
///         contract has no receive()).
contract GoodStreamEscrow is ReentrancyGuard {
    // ---------------------------------------------------------------------
    // Constants
    // ---------------------------------------------------------------------

    uint256 public constant PERIOD = 30 days;
    uint64 public constant CHALLENGE_WINDOW = 48 hours;

    // ---------------------------------------------------------------------
    // Storage
    // ---------------------------------------------------------------------

    struct Pledge {
        address sender; // the sender's w3pk primary account; receives cancel and reclaim refunds
        bytes32 recipientKey; // random off-chain key, never derived from an identity
        uint128 monthly; // wei due per period
        uint32 months; // total periods locked
        uint32 released; // periods already settled into the allowance
        uint64 start; // funding time; the first period is due immediately
    }

    struct Recipient {
        uint256 allowance; // wei settled and not yet paid out
        address payout; // current payout wallet, zero until a proposal takes effect
        address pendingPayout; // proposed by the attester
        uint64 pendingUntil; // pendingPayout takes effect from this time
        bool refunding; // set by the guardian: senders can reclaim, nothing else moves
    }

    address public guardian;
    address public attester;
    uint256 public nextPledgeId = 1;

    mapping(uint256 => Pledge) public pledges;
    mapping(bytes32 => Recipient) public recipients;

    // ---------------------------------------------------------------------
    // Events
    // ---------------------------------------------------------------------

    event Funded(uint256 indexed pledgeId, address indexed sender, bytes32 indexed recipientKey, uint128 monthly, uint32 months);
    event FundedFor(uint256 indexed pledgeId, address indexed payer);
    event ToppedUp(uint256 indexed pledgeId, uint32 extraMonths);
    event Cancelled(uint256 indexed pledgeId, uint256 refunded);
    event Released(uint256 indexed pledgeId, bytes32 indexed recipientKey, uint32 releasedTotal, uint256 amount);
    event PayoutProposed(bytes32 indexed recipientKey, address indexed wallet, uint8 method, uint64 pendingUntil);
    event PayoutVetoed(bytes32 indexed recipientKey, address indexed wallet);
    event PayoutSet(bytes32 indexed recipientKey, address indexed wallet);
    event Withdrawn(bytes32 indexed recipientKey, address indexed to, uint256 amount);
    event RefundOpened(bytes32 indexed recipientKey);
    event Reclaimed(uint256 indexed pledgeId, address indexed sender, uint256 amount);
    event AttesterSet(address attester);
    event GuardianSet(address guardian);

    // ---------------------------------------------------------------------
    // Errors
    // ---------------------------------------------------------------------

    error NotGuardian();
    error NotAttester();
    error NotSender();
    error NotPayout();
    error ZeroAddress();
    error InvalidAmount();
    error PledgeEnded();
    error Refunding();
    error NotRefunding();
    error NothingPending();
    error WindowClosed();
    error NoPayout();
    error PayoutAlreadySet();
    error NothingToWithdraw();
    error TransferFailed();

    // ---------------------------------------------------------------------
    // Modifiers and constructor
    // ---------------------------------------------------------------------

    modifier onlyGuardian() {
        if (msg.sender != guardian) revert NotGuardian();
        _;
    }

    modifier onlyAttester() {
        if (msg.sender != attester) revert NotAttester();
        _;
    }

    constructor(address guardian_, address attester_) {
        if (guardian_ == address(0) || attester_ == address(0)) revert ZeroAddress();
        guardian = guardian_;
        attester = attester_;
    }

    // ---------------------------------------------------------------------
    // Senders
    // ---------------------------------------------------------------------

    /// @notice Lock `monthly * months` wei for `recipientKey`. The first month is
    ///         due immediately, then one more every PERIOD.
    function fund(bytes32 recipientKey, uint128 monthly, uint32 months)
        external
        payable
        returns (uint256 pledgeId)
    {
        pledgeId = _fund(msg.sender, recipientKey, monthly, months);
    }

    /// @notice Same as fund(), paid by the caller for a pledge owned by `sender`.
    ///         Only `sender` can top up or cancel it, and every refund goes to
    ///         `sender`. Used by a partner CASP to deliver a purchase straight
    ///         into the escrow; the caller gets no rights over the pledge.
    function fundFor(address sender, bytes32 recipientKey, uint128 monthly, uint32 months)
        external
        payable
        returns (uint256 pledgeId)
    {
        if (sender == address(0)) revert ZeroAddress();
        pledgeId = _fund(sender, recipientKey, monthly, months);
        emit FundedFor(pledgeId, msg.sender);
    }

    function _fund(address sender, bytes32 recipientKey, uint128 monthly, uint32 months)
        internal
        returns (uint256 pledgeId)
    {
        if (recipientKey == bytes32(0) || monthly == 0 || months == 0) revert InvalidAmount();
        if (msg.value != uint256(monthly) * months) revert InvalidAmount();
        if (recipients[recipientKey].refunding) revert Refunding();

        pledgeId = nextPledgeId++;
        pledges[pledgeId] = Pledge({
            sender: sender,
            recipientKey: recipientKey,
            monthly: monthly,
            months: months,
            released: 0,
            start: uint64(block.timestamp)
        });

        emit Funded(pledgeId, sender, recipientKey, monthly, months);
    }

    /// @notice Add months to a pledge that still has periods to come.
    function topUp(uint256 pledgeId, uint32 extraMonths) external payable {
        Pledge storage p = pledges[pledgeId];
        if (msg.sender != p.sender) revert NotSender();
        if (recipients[p.recipientKey].refunding) revert Refunding();
        if (extraMonths == 0 || msg.value != uint256(p.monthly) * extraMonths) revert InvalidAmount();

        _release(pledgeId, p);
        if (p.released >= p.months) revert PledgeEnded(); // every period already due: fund a new pledge
        p.months += extraMonths;
        emit ToppedUp(pledgeId, extraMonths);
    }

    /// @notice Stop a pledge. Months already due go to the recipient's allowance;
    ///         the rest comes back to the sender.
    function cancel(uint256 pledgeId) external nonReentrant {
        Pledge storage p = pledges[pledgeId];
        if (msg.sender != p.sender) revert NotSender();
        if (recipients[p.recipientKey].refunding) revert Refunding(); // use reclaim()

        _release(pledgeId, p);
        uint256 refund = uint256(p.monthly) * (p.months - p.released);
        if (refund == 0) revert PledgeEnded();
        p.months = p.released;

        emit Cancelled(pledgeId, refund);
        _send(p.sender, refund);
    }

    // ---------------------------------------------------------------------
    // Settlement: what is due is computed from time, never triggered
    // ---------------------------------------------------------------------

    /// @notice Number of periods due now for a pledge and not yet settled.
    function releasable(uint256 pledgeId) public view returns (uint32) {
        Pledge storage p = pledges[pledgeId];
        if (p.released >= p.months || recipients[p.recipientKey].refunding) return 0;
        uint256 due = (block.timestamp - p.start) / PERIOD + 1; // first period at start
        if (due > p.months) due = p.months;
        return due > p.released ? uint32(due - p.released) : 0;
    }

    function _release(uint256 pledgeId, Pledge storage p) internal returns (uint256 amount) {
        uint32 n = releasable(pledgeId);
        if (n == 0) return 0;
        p.released += n;
        amount = uint256(p.monthly) * n;
        recipients[p.recipientKey].allowance += amount;
        emit Released(pledgeId, p.recipientKey, p.released, amount);
    }

    // ---------------------------------------------------------------------
    // Recipients
    // ---------------------------------------------------------------------

    /// @notice Called by the attester after a recorded off-chain verification.
    ///         The wallet takes effect once CHALLENGE_WINDOW has passed without a
    ///         veto. Also used to change a payout wallet: the current one stays
    ///         active until the new proposal takes effect.
    /// @param method 1 YouTube, 2 Twitch, 3 Instagram, 4 email.
    function proposePayout(bytes32 recipientKey, address wallet, uint8 method) external onlyAttester {
        if (wallet == address(0)) revert ZeroAddress();
        Recipient storage r = recipients[recipientKey];
        if (r.refunding) revert Refunding();
        _applyPending(recipientKey, r); // a proposal past its window takes effect before being replaced

        uint64 until = uint64(block.timestamp) + CHALLENGE_WINDOW;
        r.pendingPayout = wallet;
        r.pendingUntil = until;
        emit PayoutProposed(recipientKey, wallet, method, until);
    }

    /// @notice Guardian cancels a pending proposal while its window is open.
    function veto(bytes32 recipientKey) external onlyGuardian {
        Recipient storage r = recipients[recipientKey];
        address wallet = r.pendingPayout;
        if (wallet == address(0)) revert NothingPending();
        if (block.timestamp >= r.pendingUntil) revert WindowClosed();
        delete r.pendingPayout;
        delete r.pendingUntil;
        emit PayoutVetoed(recipientKey, wallet);
    }

    /// @notice The payout wallet in effect now (including a proposal past its window).
    function payoutOf(bytes32 recipientKey) external view returns (address) {
        Recipient storage r = recipients[recipientKey];
        if (r.pendingPayout != address(0) && block.timestamp >= r.pendingUntil) return r.pendingPayout;
        return r.payout;
    }

    /// @notice Public: anyone can push what is due to the recipient's payout
    ///         wallet. Settles the given pledges first. Funds only go to the
    ///         payout wallet, so GoodStream's relayer can pay the gas.
    function payout(bytes32 recipientKey, uint256[] calldata pledgeIds)
        external
        nonReentrant
        returns (uint256 amount)
    {
        address to = _applyPending(recipientKey, recipients[recipientKey]);
        if (to == address(0)) revert NoPayout();
        amount = _collect(recipientKey, pledgeIds);
        emit Withdrawn(recipientKey, to, amount);
        _send(to, amount);
    }

    /// @notice Only the payout wallet: pull what is due to any address. Settles
    ///         the given pledges first. The recipient pays the gas.
    function withdraw(bytes32 recipientKey, address to, uint256[] calldata pledgeIds)
        external
        nonReentrant
        returns (uint256 amount)
    {
        if (to == address(0)) revert ZeroAddress();
        address wallet = _applyPending(recipientKey, recipients[recipientKey]);
        if (wallet == address(0)) revert NoPayout();
        if (msg.sender != wallet) revert NotPayout();
        amount = _collect(recipientKey, pledgeIds);
        emit Withdrawn(recipientKey, to, amount);
        _send(to, amount);
    }

    /// @dev Promotes a pending proposal whose window has passed; returns the payout wallet.
    function _applyPending(bytes32 recipientKey, Recipient storage r) internal returns (address) {
        address wallet = r.pendingPayout;
        if (wallet != address(0) && block.timestamp >= r.pendingUntil) {
            r.payout = wallet;
            delete r.pendingPayout;
            delete r.pendingUntil;
            emit PayoutSet(recipientKey, wallet);
        }
        return r.payout;
    }

    /// @dev Settles the given pledges of `recipientKey` and empties its allowance.
    function _collect(bytes32 recipientKey, uint256[] calldata pledgeIds) internal returns (uint256 amount) {
        for (uint256 i; i < pledgeIds.length; ++i) {
            Pledge storage p = pledges[pledgeIds[i]];
            if (p.recipientKey == recipientKey) _release(pledgeIds[i], p);
        }
        Recipient storage r = recipients[recipientKey];
        amount = r.allowance;
        if (amount == 0) revert NothingToWithdraw();
        r.allowance = 0;
    }

    // ---------------------------------------------------------------------
    // Refunds (unclaimed after 12 months, or recipient objection)
    // ---------------------------------------------------------------------

    /// @notice Freeze a recipient that never got a payout wallet so senders can
    ///         take everything back. Because no payout was ever set, nothing was
    ///         paid out, and each pledge's settled share is still in the allowance.
    function openRefund(bytes32 recipientKey) external onlyGuardian {
        Recipient storage r = recipients[recipientKey];
        if (r.refunding) revert Refunding();
        if (_applyPending(recipientKey, r) != address(0)) revert PayoutAlreadySet();

        r.refunding = true;
        delete r.pendingPayout;
        delete r.pendingUntil;
        emit RefundOpened(recipientKey);
    }

    /// @notice Return a pledge's full contribution (settled + unsettled) to its
    ///         sender. Anyone can trigger it; funds only go to the sender.
    function reclaim(uint256 pledgeId) external nonReentrant {
        Pledge storage p = pledges[pledgeId];
        Recipient storage r = recipients[p.recipientKey];
        if (!r.refunding) revert NotRefunding();

        uint256 amount = uint256(p.monthly) * p.months;
        if (amount == 0) revert NothingToWithdraw();
        r.allowance -= uint256(p.monthly) * p.released;
        p.months = 0;
        p.released = 0;

        emit Reclaimed(pledgeId, p.sender, amount);
        _send(p.sender, amount);
    }

    // ---------------------------------------------------------------------
    // Guardian admin
    // ---------------------------------------------------------------------

    function setAttester(address attester_) external onlyGuardian {
        if (attester_ == address(0)) revert ZeroAddress();
        attester = attester_;
        emit AttesterSet(attester_);
    }

    function setGuardian(address guardian_) external onlyGuardian {
        if (guardian_ == address(0)) revert ZeroAddress();
        guardian = guardian_;
        emit GuardianSet(guardian_);
    }

    // ---------------------------------------------------------------------
    // Internal
    // ---------------------------------------------------------------------

    function _send(address to, uint256 amount) private {
        (bool ok,) = to.call{value: amount}("");
        if (!ok) revert TransferFailed();
    }
}
```

### 9.3 Gas on mainnet

Mainnet gas is the main running cost:

- **Sender transactions** (`fund`, `topUp`, `cancel`) are sent and paid by the sender's own account, from the gas reserve included in each purchase or transfer (§10.2). A monthly-payment stream costs one `fund` per month; a budget stream costs one `fund` in total. With a partner CASP, the partner sends `fundFor` and passes its gas on in the price of each purchase (§10.8).
- **Nothing runs monthly** on GoodStream's side, so there's no recurring gas for releases.
- **Recipient-side transactions are paid by GoodStream, permanently.** The attester pays for `proposePayout` (only the attester can send it) and the relayer pays for relayed `payout` calls. Recipients never pay a fee and never sign anything for gas. Both wallets hold a small float topped up from GoodStream's treasury Safe, which the voluntary support transfers feed (§10.4.3). Relayed payouts are rate-limited so the relayer can't be drained (§12.1). A recipient who prefers to call `withdraw` themselves pays their own gas. The contract takes no fee.
- The app warns when a pledge is too small to be worth the gas.

## 10. Flows

### 10.1 Sender workflow

The sender thinks in euros per month; ETH and the escrow stay in the background.

**Step 1 — Pick a recipient.** On the home page, the sender pastes a YouTube, Twitch or Instagram link, or an email address. `GET /api/recipients/resolve` returns `{recipientKey, preview}` and the app shows the preview card (§7.2). The sender confirms "Yes, that's them".

**Step 2 — Choose an amount and how to pay.** The sender picks **a monthly amount in euros** (presets €1, €5, €10, €20, or custom) and **a payment method**: **Card** or **ETH I already own**. How the stream is paid follows from these (§10.2.1):

- **Card, more than €10 a month → monthly payments.** No budget to choose: Stripe charges one month at a time, a few days before each month falls due, until the sender stops (§10.1.1). A "Pay several months upfront instead" link switches to a budget.
- **Card at €10 a month or less, or ETH I already own → budget.** The sender also picks **a budget** (at least `minEUR`, §10.2; presets €20, €50, €100, or custom), paid once. The duration follows from the amount and budget: as many whole months as the budget covers.

The app calculates what's needed (§10.2) and shows one summary. For a budget:

```text
Support @lemediaindé with €5/month

  For the creator          €20.00   (4 months: €5 now, then €5 each month)
  Network fees             €x.xx    (Ethereum gas, estimated)
  Stripe fees              €x.xx    (card only, from Stripe's live quote)
  ─────────────────────────────────
  You pay                  €xx.xx   (card)   or   x.xxxx ETH to send (own ETH)

  Cancel any time: whatever isn't due yet comes back to you.
```

For monthly payments:

```text
Support @lemediaindé with €20/month

  For the creator          €20.00 / month   (first month now)
  Network fees             €x.xx  / month   (Ethereum gas, estimated)
  Stripe fees              €x.xx  / month   (from Stripe's live quote)
  ─────────────────────────────────
  You pay                  €xx.xx / month   (confirmed each month, a few days before it's due)

  Stop any time. Nothing is paid in advance beyond the current month.
```

**Step 3 — Create a passkey.** First-time senders create a w3pk passkey (Face ID, Touch ID or Windows Hello). Their primary account becomes their GoodStream wallet (§6). No seed phrase, no extension. Returning senders just sign in with their passkey. Monthly-payment senders also give an email address, which the reminders need (§10.1.1).

**Step 4 — Fund the wallet.** One of two paths, as chosen in step 2:

- **4a. Pay by card.** The app creates an onramp session on the backend with the destination wallet set to the sender's primary account and locked, the network set to Ethereum, the currency set to ETH, and the euro amount from step 2 pre-filled (the budget, or the first month for monthly payments). Stripe's embedded widget opens inside GoodStream.
  - *First purchase:* the sender creates a Link account (email and phone), completes Stripe's identity verification, then pays by card, Apple Pay or Google Pay. For EU buyers, Stripe requires an ID document and a selfie before any purchase, plus the tax and national identifiers MiCA and CARF call for ([Stripe EU KYC guide](https://docs.stripe.com/crypto/onramp/eu-kyc-integration-guide)). Expect a few minutes; this is the main drop-off point.
  - *Returning purchase:* Link recognises them; payment takes a few taps. This is what every later monthly payment looks like.
  - Stripe shows its final quote (ETH amount, fees) before the sender confirms.
- **4b. Use ETH I already own.** The app shows the sender's GoodStream wallet address with a QR code and the exact ETH amount to send (pledge plus gas reserve, §10.2). The sender sends it from any wallet or exchange they already use. The app states plainly that it must be **ETH on Ethereum mainnet**: other networks or tokens won't be detected. No Stripe, no KYC, no onramp fee. If the account already holds enough ETH (leftovers, or a previous transfer), the sender skips straight to step 6.

Senders Stripe can't serve (country, IP, failed KYC) are offered path 4b. There's no second card ramp in v1 (§10.7).

**Step 5 — Wait for the ETH.** The app shows "Your ETH is on its way" and watches the account balance (polled every few seconds while the page is open). For card purchases, Stripe delivers once KYC is done and webhooks update the progress display; it usually takes a minute or two. For own-ETH transfers, it depends on the sending wallet or exchange (exchange withdrawals can take longer).

**Step 6 — Confirm the pledge.** The app sizes the pledge from the ETH that actually arrived (§10.2) and shows the final summary: monthly amount, number of months (one for monthly payments), recipient, schedule, network fee. The sender approves with their passkey and the app sends one transaction (§10.3) from their account. A confirmation screen shows the schedule (first month due now, next dates listed) and the share link for the recipient.

**Step 7 — Manage.** From the dashboard, the sender can:

- **top up** a budget stream (back to step 4, by card or with their own ETH, then `topUp` to add months);
- **change** the monthly amount: for monthly payments, it takes effect from the next payment, with nothing to cancel; for a budget, cancel then fund a new pledge (two passkey approvals);
- **stop** a monthly-payment stream (no more reminders or payments; the current month stays with the creator) or **cancel** a budget pledge (ETH not yet due comes back to their account);
- **send** leftover ETH from their account to any address.

For budget streams, the app warns by email (if given) and in-app 7 days and 1 day before the last monthly amount becomes due, and offers to switch to monthly payments when the amount allows it.

#### 10.1.1 Monthly payments

For card streams above €10 a month, the sender pays one month at a time, so Stripe's fixed costs are charged on amounts large enough to absorb them and nothing sits in the escrow ahead of time.

```text
3 days before the next date ──► email + in-app: "Your €20 for @lemediaindé is due on 12 Dec. Confirm"
Sender opens the link ──► signs in with their passkey
  ├─ Stripe onramp, returning purchase: saved card, Link one-tap, no new KYC ──► ETH lands in their account
  └─ app waits for the ETH, then asks for one passkey approval ──► escrow.fund(key, m, 1)
Month due immediately in the escrow ──► recipient collects whenever they want
```

- **Schedule.** Each stream keeps its own date (the day of the first payment). The reminder goes out 3 days before; paying early just makes that month due early. If the sender hasn't paid, reminders follow on the date and 3 days after; after 7 days the stream is marked lapsed and the sender is told how to resume. A lapsed stream costs nothing and loses nothing.
- **One pledge per payment.** Each month is a new one-month pledge (`fund(key, m, 1)`), converted from euros at that month's price. The recipient's euro amount stays steady from month to month, and the contract needs no change. The relayer includes the new pledge IDs in the next payout.
- **Why not fully automatic with Stripe.** Stripe can't send the ETH straight into the escrow: it delivers to a wallet address, while `fund` and `fundFor` need the recipient key in their calldata, and the contract has no `receive()`. The Stripe onramp only offers a fast checkout for returning customers, not purchases charged without the buyer present, and GoodStream charging the card itself would make it the seller of the ETH (§2). The w3pk account also signs only after a passkey approval. So with Stripe, monthly payments need one tap and one passkey approval a month. If Stripe confirms an off-session onramp purchase is possible (§15.2), this can shrink to a single approval.
- **Fully automatic with a partner CASP.** A partner charges the saved card or SEPA mandate itself and calls `fundFor` with the sender's address as owner, so each month arrives in the escrow with nothing for the sender to do but read the receipt (§10.8). Stopping the stream in GoodStream cancels the partner subscription through its API; the sender can also cancel it with the partner directly.

### 10.2 Fees and amounts

GoodStream charges **no fee**. Everything the sender pays goes to Stripe (onramp fees, card path only), to Ethereum validators (gas), or to the recipient.

**Inputs**

| Symbol | Meaning | Source |
| --- | --- | --- |
| `M` | Monthly amount in EUR chosen by the sender | Step 2 |
| `B` | Budget in EUR chosen by the sender, at least `minEUR` (budget streams only) | Step 2 |
| `T` | Monthly-payment threshold in EUR, default €10 | Configuration, reviewed against live Stripe quotes |
| `P` | ETH/EUR mid-market price | Price API, display only |
| `G` | Gas reserve for the pledge transaction, in ETH | `gasUnits × (baseFee + tip) × 1.3`, with `gasUnits` measured on a mainnet fork for `fund` |
| `S(x)` | Stripe onramp quote for receiving `x` ETH: transaction fee, network fee and spread (card path only) | Stripe onramp quote, fetched by the backend |

#### 10.2.1 Monthly payments or budget

```text
monthly payments   if path = card and M > T        (unless the sender picks "pay several months upfront")
budget             otherwise                        (own ETH, or M ≤ T)
```

The threshold keeps each card purchase large enough that Stripe's fixed costs (its network fee and any fixed part of its transaction fee) plus `G` stay under 10% of the amount. It starts at €10 and is adjusted once live Stripe EU quotes are known, never below €10. Below it, a budget spreads those fixed costs over several months. Each onramp provider has its own threshold: with a partner CASP, the fixed cost per payment falls to about €0.25 to €0.35 (§10.8), so the threshold can drop to around €5 and monthly payments become the default for nearly every card stream.

**Monthly payments through a partner CASP (each month)**

```text
amount charged     EUR = M + G_EUR + A(M) + s × M       # A = card or SEPA fee, s = partner spread
delivered          partner calls fundFor{value: m}(senderAccount, key, m, 1)
where              A(M) ≈ 1.5% × M + €0.25 (standard EEA card) or ≈ €0.35 (SEPA Direct Debit)
```

**Monthly payments through Stripe (each month)**

```text
ETH needed         E   ≈ M / P + G
amount to pay      EUR = Stripe quote S(E).total
pledge             m   = D − G,  fund(key, m, 1)        # D = ETH available for this payment
```

**Budget: before funding (estimate shown in step 2)**

```text
months             N   = floor(B / M)                      # budget rounded down to whole months
ETH needed         E   ≈ (N × M) / P + G
card:  amount to pay   EUR = Stripe quote S(E).total       # includes Stripe fees and delivery gas
own ETH: amount to send    E − (ETH already in the account) # no Stripe fees
```

**Budget: after delivery (exact, shown in step 6)**

```text
available          D   = ETH in the account for this pledge (delivered by Stripe, sent in, or already there)
pledge             E_p = D − G                               # G re-estimated at signing time
monthly (wei)      m   = floor(E_p / N)
locked             m × N                                     # rounding dust stays in the sender's account
```

The pledge is sized from the ETH that's actually there, so there's no recalculation threshold to manage: the confirmation in step 6 always matches what's in the account. A budget's monthly amount is converted to ETH **once**, at that point; after that, the pledge runs in ETH and the euro value the recipient receives moves with the ETH price (§10.5). Monthly payments are converted each month, so their euro value stays close to `M`. The dashboard shows both.

**What the sender sees.** The summary lines in step 2: amount for the creator (`N × M`, or `M` per month), network fees (`G` in EUR), Stripe fees for the card path (`S(E).total − (E × quoted price)`, i.e. Stripe's transaction fee, delivery network fee and spread), and the total (in EUR for card, in ETH for own ETH).

**Minimum budget.** For budget streams, gas and, for the card path, Stripe's network fee are fixed costs per pledge, so the app enforces a minimum **budget** where they stay under 10% of the total: `minEUR = (G_EUR + StripeNetworkFee_EUR) / 0.10` for card and `G_EUR / 0.10` for own ETH, recomputed hourly from gas prices, with a floor of €20. The monthly amount has no minimum: a small monthly amount just means more months, and the sender can cancel any time to take back whatever isn't due yet.

**GoodStream side.** Payout proposals and relayed payouts are paid by GoodStream, permanently (§9.3). A recipient can always call `withdraw` and pay their own gas instead.

**Examples** (illustrative only: plug in live values). Budget: €1/month with a €20 budget runs for 20 months. During the third month, €3 worth of ETH (at the pledge-time price) is due to the recipient; if the sender cancels then, the other €17 worth comes back to their account. Monthly payments: €20/month by card means one Stripe purchase of about €20 plus fees each month, a few days before the date; nothing more is ever held in the escrow. The real Stripe EU fee schedule is only visible in live quotes after approval; third-party comparisons estimate it from about 1.5%, plus network fee.

### 10.3 Funding transaction

One transaction from the sender's primary account, approved with their passkey and paid from the gas reserve, whichever way the ETH arrived:

```text
escrow.fund{value: m × N}(recipientKey, m, N)      # N = 1 for each monthly payment
```

After the first one confirms, the app gives the sender a share link, `goodstream.in/<platform>/<id>`, to send to the recipient. Email recipients who haven't opted in get one notification (§11.4).

If a recipient has opted out (§11.4), `resolve` refuses new pledges to them, and active monthly-payment streams to them stop.

### 10.4 Recipient: opt-in, claim and withdrawal

Recipients are **opt-in**. A recipient is opted in once they've signed in with w3pk and proven control of their identity (§8); GoodStream records `opted_in_at` and the attester proposes their wallet as the payout address. There are two ways to get there.

#### 10.4.1 Self-registration

A creator doesn't have to wait for a pledge:

```text
Creator opens "I'm a creator" ──► reads the privacy notice, creates a w3pk wallet (or signs in) + SIWE session
  ├─ picks a platform and logs in with YouTube / Twitch / Instagram, or enters an email and clicks the magic link
Backend checks proof ──► creates the recipient key if none exists, sets opted_in_at
                     ──► attester calls escrow.proposePayout(key, w3pk primary account, method)
                     ──► 48 h challenge window (guardian may veto)
Creator gets their public page goodstream.in/<platform>/<id> with an "On GoodStream" badge, to share with their audience
```

Because the payout wallet is set up front, pledges made after registration can be collected as soon as they're due, with no waiting window.

#### 10.4.2 Opt-in at claim time

A creator designated by a sender opts in simply by logging in to claim:

```text
Recipient opens goodstream.in/youtube/UCxxxx ──► "You have 0.0412 ETH waiting (≈ €…)"
  ├─ reads the privacy notice, creates a w3pk wallet (or signs in) + SIWE session
  ├─ logs in with YouTube / Twitch / Instagram, or clicks the email magic link  ──► now opted in
Backend checks proof ──► sets opted_in_at, attester calls escrow.proposePayout(key, w3pk primary account, method)
                     ──► 48 h challenge window (guardian may veto)
```

#### 10.4.3 Collecting

```text
Recipient clicks "Collect" any time after the window
  ├─ default: relayer calls payout(key, pledgeIds) ──► ETH in their payout wallet (GoodStream pays gas)
  └─ or: recipient calls withdraw(key, to, pledgeIds) ──► ETH to any address (recipient pays gas)
Once the ETH has arrived ──► optional "Support GoodStream" suggestion
```

Each call settles every month due on the recipient's pledges (IDs from the `pledges` table or the `Funded` events), records the payout wallet the first time, and sends the whole allowance. A recipient who already has a payout wallet just collects whenever they like; new months keep becoming due on the same pledges, and new monthly payments add new pledges.

Relayed payouts are free for the recipient but limited to keep the relayer from being drained (§12.1): at most one per recipient every 7 days, and only when the amount is worth at least 20 times the gas. Below that, the app shows when the next free payout is available, and the recipient can still call `withdraw` and pay the gas themselves.

**Support GoodStream.** After a successful collect, and only then, the app shows a short, skippable card: "GoodStream takes no fee. If it helps you, you can support it." Options: no preset selected, 2%, 5%, a custom amount, or a monthly pledge to GoodStream's own creator page.

- A one-off amount is one plain ETH transfer from the creator's payout wallet to GoodStream's treasury Safe, approved with their passkey. The creator pays that small gas.
- A monthly pledge uses the normal sender flow, with GoodStream as the recipient.
- It's never a condition for collecting, nothing is pre-selected, and "Not now" hides the card for 30 days. No reminders by email.
- Support received tops up the relayer and attester gas floats first (§9.3).

#### 10.4.4 What opting in changes

- **Preview card.** Senders see the "On GoodStream" badge (§7.2).
- **No unclaimed refund.** A payout wallet is in effect, so the 12-month unclaimed refund (§12.4) no longer applies.
- **Data.** The recipient is now a user with an account: the legal basis becomes the contract, and the rules for people who haven't opted in (§11.4) stop applying.
- **Leaving.** An opted-in recipient can still opt out: new pledges are refused, monthly-payment streams to them stop, and their senders are notified so they can cancel and take back whatever isn't due yet. Months already due stay collectable.

### 10.5 ETH price exposure

Pledges and allowances are in ETH. Senders give, and recipients receive, an ETH amount whose euro value moves with the market. Monthly payments reset the euro amount each month, so the exposure only lasts until the recipient collects; budgets are exposed from funding onwards. The app always shows EUR estimates and says so plainly on the pledge and claim screens.

### 10.6 Scheduled jobs

All run in `genji-worker` (§4.1) and are idempotent. None of them is needed for money already pledged to move.

| Job | Frequency | What it does |
| --- | --- | --- |
| Minimum budget and threshold | Hourly | Recomputes `minEUR` for both funding paths from gas prices, and checks that the monthly-payment threshold `T` still keeps fixed costs under 10% (§10.2) |
| Monthly payment reminders | Hourly | For each active monthly-payment stream: email and in-app reminder 3 days before the date, on the date and 3 days after; marks the stream lapsed after 7 days without payment and tells the sender |
| Balance warnings | Daily | For budget streams, emails and in-app notices 7 days and 1 day before the last monthly amount becomes due; 30 and 90 days without a claim |
| Gas floats | Hourly | Alerts operators when the relayer or attester balance falls below a few days of expected use |
| Profile refresh | Daily, batched | Refreshes each recipient profile at least monthly |
| Retention | Hourly | Deletes data past its retention period (§11.3) |
| Refund eligibility | Daily | Flags recipient keys that haven't opted in after 12 months for guardian review (§12.4) |

### 10.7 Onramp comparison

Checked in November 2026 against the providers' own pages, to see whether another onramp would be cheaper than Stripe or would let small purchases skip the ID check. Fees are the provider's published card prices in euros, before gas and before any spread built into the exchange rate.

| Provider | Card fee | Fee on a €10 payment | Fee on a €20 payment | KYC for a first purchase in Europe | MiCA |
| --- | --- | --- | --- | --- | --- |
| **Stripe** | Not published for the EU; visible in live quotes after approval | Unknown | Unknown | ID document and selfie mandatory for all EU users, plus tax and national identifiers; wallet ownership check from €1,000 ([guide](https://docs.stripe.com/crypto/onramp/eu-kyc-integration-guide)) | To ask during the application (§13) |
| **[Ramp Network](https://support.rampnetwork.com/en/articles/10415-what-fees-are-charged-when-buying-crypto)** | Up to 3.9%, minimum up to €2.49; custom pricing for partners | Up to €2.49 (25%) | Up to €2.49 (12.5%) | ID document for every purchase; proof of address above €5,000. France, Italy and the Netherlands have their own table ([limits](https://support.rampnetwork.com/en/articles/441-what-are-the-kyc-limits-and-requirements)) | Ramp Swaps (Ireland), MiCA CASP, listed by the AMF for France since 2 December 2025 |
| **[MoonPay](https://www.moonpay.com/es/legal/europe_pricing_disclosure)** | Up to 4.5% when referred by a partner, minimum €3.99; a spread may be built into the price, plus a possible partner "ecosystem fee" | About €3.99 (40%) | About €3.99 (20%) | ID and liveness selfie, tax number and a questionnaire at the lowest EEA tier ([tiers](https://dev.moonpay.com/platform/guides/verification-tiers)) | MiCA licence in the Netherlands |
| **[Transak](https://support.transak.com/en/articles/7845942-how-does-transak-calculate-prices-and-fees)** | 3.5% + €1 (EUR cards); Apple Pay and Google Pay 3.5%, minimum €1; SEPA transfer 0.99%, minimum €1 | €1.35 (13.5%) | €1.70 (8.5%) | Three levels. Simple KYC (name, phone, date of birth, address, no ID or selfie) covers $10 to $200 per transaction, but some countries aren't eligible: the API's `isLightKycAllowed` flag tells. Standard KYC adds photo ID and a live selfie ([levels](https://docs.transak.com/guides/transak-different-kyc-levels)). Offers KYC reliance, reusing KYC a partner already did | Describes itself as a registered VASP in the EU; check its MiCA status on the ESMA register |
| **[Mercuryo](https://help.mercuryo.io/hc/en-gb/articles/30404513537565)** | Up to 5.5%, minimum €1 (cards and mobile pay); bank transfer up to 3%, minimum €2; plus a separate "infrastructure fee" | €1 or more (10%+) | Up to €1.10 (5.5%) or more | Mandatory above a KYC threshold that the docs don't publish; done by SumSub (ID document and liveness), with an option to reuse a partner's SumSub verification ([KYC docs](https://widget.docs.mercuryo.io/guide/features/kyc)). Its 2022 offer of purchases up to €900 without KYC predates MiCA | Check on the ESMA register |
| **Partner CASP** (§10.8) | Card or bank fee only, plus a small negotiated spread: about 1.5% + €0.25 for a standard EEA card on Stripe's public pricing, about €0.35 for SEPA Direct Debit | About €0.40 (4%) by card, €0.35 (3.5%) by SEPA | About €0.55 (2.75%) by card, €0.35 (1.75%) by SEPA | Identification and verification required, but done once; eID can replace the document and selfie (see below) | Required by definition |

**KYC can't be skipped, only made lighter.** Every licensed seller has to identify the buyer:

- **France today.** Since the 2020 ordinance, French rules require PSAN to identify every client, including occasional ones, from the first euro ([ADAN summary](https://adan.eu/en/publication/french-digital-assets-service-providers-dasp-regime-adjustments/)). That's why "light KYC" tiers are often not offered to French buyers.
- **EU from 10 July 2027.** The AML Regulation (2024/1624) applies directly. Opening an account means full customer due diligence, and below €1,000 an occasional purchase still requires identifying the customer and verifying their identity ([summary](https://didit.me/blog/amlr-crypto-casp-requirements/)).
- **Lighter route.** Verification doesn't have to be a document and a selfie: the AMLR also accepts electronic identification at substantial or high assurance. In France that means France Identité or the EU Digital Identity Wallet. A partner that accepts eID makes the first purchase a two-minute step, and later purchases need nothing.

**Conclusion.**

- None of the five lets a French buyer skip identification. Transak's Simple KYC may work in some EEA countries for small amounts, but not reliably for GoodStream's main audience.
- On cost, Transak and Mercuryo beat Ramp Network and MoonPay on small amounts thanks to €1 minimums, but still take 8% to 14% of a €10–20 payment.
- At launch, GoodStream uses Stripe's onramp, with the own-ETH path as the fallback. If Stripe's approval fails or its quotes are worse, Transak is the first fallback. It has the lowest fixed fee, KYC reliance, and SEPA at 0.99%.
- The target is a partner CASP (§10.8). It's the only option where the onramp itself costs close to nothing and monthly payments can run without the sender.

### 10.8 Partner CASP: near-zero onramp and automatic monthly payments

Card and bank fees can't be avoided, but the onramp's own margin can be. Retail onramps charge 3.5% to 5.5% plus minimums. Card acquiring alone costs about 1.5% + €0.25 for a standard EEA card ([Stripe EEA pricing](https://support.stripe.com/questions/pricing-updates-for-businesses-based-in-the-european-economic-area-(eea))), and SEPA Direct Debit about €0.35 per payment. The rest is the seller's margin. GoodStream's target is a partnership with a MiCA-authorised CASP that sells ETH at the market price plus a small negotiated spread, and charges payments on its own merchant account.

**Who does what**

| | Partner CASP | GoodStream |
| --- | --- | --- |
| Sells the ETH, merchant of record | Yes | No |
| Collects euros (card, Apple Pay, Google Pay, SEPA Direct Debit) | Yes, on its own merchant account and acquirer | Never receives or forwards euros |
| KYC and AML (identification, Travel Rule, sanctions screening) | Yes | No; passes only what the partner asks for, with the sender's consent |
| Saved card or SEPA mandate, monthly charges | Yes (card: customer authentication at setup, then merchant-initiated charges; SEPA: mandate) | Tells the partner the stream's amount, date, sender address and recipient key |
| Delivery | Calls `escrow.fundFor{value: m}(senderAccount, recipientKey, m, 1)`, or for a budget `fundFor(…, m, N)`. Can also deliver to the sender's account like Stripe does | Watches `Funded`/`FundedFor` events and updates the stream |
| Cancel and refund rights on the pledge | None | None; they belong to the sender's w3pk account, as with every pledge |

**Monthly flow**

```text
Sender sets up a €20/month stream ──► partner widget or API: KYC once (eID or document), saves card or SEPA mandate
Each month, on the stream's date:
  partner charges €20 + costs ──► buys ETH ──► fundFor(senderAccount, key, m, 1) ──► month due in the escrow
  GoodStream emails a receipt; nothing for the sender to approve
Stop in GoodStream ──► GoodStream cancels the partner subscription by API (the sender can also cancel with the partner)
Failed charge ──► partner retries once; GoodStream reminds the sender as for a missed payment (§10.1.1)
```

**Costs.** The amount charged is `M + G_EUR + A(M) + s × M` (§10.2): the card or SEPA fee `A`, the gas for `fundFor`, and the partner's spread `s`. The negotiating target is a spread of 0.5% or less. Paid in ETH from the partner's own inventory or exchange account, the ETH leg itself costs close to nothing. For a €20 month by standard EEA card, that's about €0.55 plus gas and spread, compared with €1.10 to €3.99 at the retail onramps (§10.7). By SEPA Direct Debit, it's about €0.35.

**What to look for in a partner**

- A MiCA authorisation for exchange of crypto-assets for funds, passported to France, on ESMA's MiCA register. If it delivers into the escrow on the customer's behalf, also an authorisation for transfer services.
- An API with server-side subscriptions: saved cards with merchant-initiated charges, and ideally SEPA Direct Debit.
- Delivery by contract call (`fundFor`), not only plain transfers.
- eID accepted for verification, and KYC reliance or reuse so GoodStream's flow stays in one place.
- A spread of 0.5% or less, no minimum fee, and a fixed fee no higher than its acquirer's.
- Its own card acquiring arrangement: Stripe requires crypto businesses to get explicit approval before onboarding ([crypto supportability](https://support.stripe.com/questions/crypto-supportability-and-availability-by-region)).
- Willingness to take the SEPA Direct Debit return risk: refunds are possible for 8 weeks, while ETH delivery is final. A partner may delay the first SEPA purchases or limit amounts.

Transak, Mercuryo and Ramp Network all advertise partner pricing or KYC reuse, so they're worth asking alongside smaller EU CASPs. The criteria above decide, not the brand.

**Open legal points (§13).**

- Whether the partner, by delivering into the escrow instead of to the buyer's own wallet, is providing a transfer service, and how the Travel Rule applies. The escrow is a contract, not the buyer's self-hosted wallet; the pledge's owner is the buyer's address.
- That GoodStream, by relaying amounts and dates to the partner, isn't collecting funds or acting as a payment agent.
- Who handles chargebacks on ETH already delivered. That's normally the partner, as merchant of record.

**Rollout.**

- `fundFor` ships in the first contract.
- The backend talks to onramps through one `OnrampProvider` interface. Once a partner is signed, new monthly streams go to the partner by default, and Stripe stays for countries or payment methods the partner doesn't cover.
- Existing Stripe monthly streams are offered a one-tap switch.
- Budgets remain for own-ETH senders and very small amounts.

## 11. GDPR

GoodStream is the controller for the personal data it processes off-chain and for what it writes on-chain. The design follows the [GDPR](https://en.wikipedia.org/wiki/General_Data_Protection_Regulation) principles of data protection by design and by default (Art. 25) and the EDPB's [Guidelines 02/2025](https://www.edpb.europa.eu/our-work-tools/documents/public-consultations/2025/guidelines-022025-processing-personal-data_en) on blockchain.

### 11.1 Principles applied

- **Nothing identifying on-chain.** On-chain data is limited to random recipient keys, wallet addresses, amounts and a method code. No handle, channel ID, email or hash of them is ever written on-chain (§7.1, §9.1). The EDPB treats even encrypted or hashed data as personal and advises keeping personal data off-chain wherever possible.
- **Wallet addresses are personal data.** They can't be avoided on a public chain, so GoodStream minimises what it links to them off-chain and says so in the privacy notice.
- **No biometrics reach GoodStream.** Passkeys are verified on the user's device; the backend only sees public keys and signatures.
- **Minimal profiles.** GoodStream keeps the least creator data it needs and refreshes it from the platform rather than building profiles.
- **Third parties keep their own data.** KYC and card data stay with Stripe or the partner CASP (independent controllers); OAuth tokens are never stored.

### 11.2 Processing register (Art. 30)

| Purpose | Data subjects | Data | Legal basis |
| --- | --- | --- | --- |
| Sender account | Senders | w3pk primary address, email (optional for budgets, required for monthly payments), timestamps | Contract (Art. 6(1)(b)) |
| Onramp tracking | Senders using the card path | Provider, onramp session or partner subscription ID, status, amounts, destination address | Contract |
| Partner hand-off | Senders using a partner CASP | Sender address, recipient key, amount, date and, with the sender's consent, the identity data the partner asks for | Contract |
| Streams and pledges | Senders | Stream ID, mode, monthly amount, next date, pledge IDs, sender address, recipient key, amounts, schedule | Contract |
| Monthly payment reminders | Senders with monthly payments | Email, stream, next date | Contract |
| Recipient account | Recipients who opted in (registered or claimed) | w3pk address, platform, canonical ID, handle, display name, avatar URL, `opted_in_at`, optional email | Contract |
| Designating a recipient | Creators who haven't opted in | Platform, canonical ID, handle, display name, avatar URL | Legitimate interest (Art. 6(1)(f)): letting the public support creators using public profile data |
| Email notification | People designated by email who haven't opted in | Email address (temporarily), HMAC of the email | Legitimate interest, with an easy objection |
| Claim verification | Recipients | Verification method, time, wallet, hash of the evidence | Contract |
| Support suggestion | Recipients who collect | Time the card was shown or dismissed (no amounts stored off-chain) | Legitimate interest |
| Security logs | All users | IP address, user agent, request metadata | Legitimate interest (security) |

A **legitimate interest assessment** is documented for the "legitimate interest" rows, and a **data protection impact assessment** (Art. 35) is carried out before launch, because the service combines a public blockchain, new technology and data about people who didn't sign up.

### 11.3 Data model with retention

SQLite schema (types simplified):

```sql
users          (owner_address PK, email NULL, created_at, last_seen_at)
streams        (stream_id PK, owner_address, recipient_key,
                mode,                                         -- 'budget' | 'monthly'
                monthly_eur, anchor_day NULL, next_due_at NULL,
                provider NULL,                                -- 'stripe' | 'partner' (card streams)
                partner_subscription_id NULL,                 -- automatic monthly payments (§10.8)
                status,                                       -- 'active' | 'lapsed' | 'stopped'
                created_at, stopped_at NULL)
onramp_sessions(id PK, owner_address, stream_id, provider, provider_session_id UNIQUE, status,
                monthly_eur, budget_eur NULL, amount_eur, delivered_wei NULL,
                created_at)                                   -- card path only
recipients     (recipient_key PK, platform, canonical_id, handle, display_name,
                avatar_url, created_at, opted_in_at NULL, opted_out_at NULL,
                support_prompt_hidden_until NULL,
                UNIQUE (platform, canonical_id))
pledges        (pledge_id PK, stream_id, owner_address, recipient_key, monthly_wei, months,
                funding_method,                               -- 'card' | 'own_eth'
                start_at, cancelled_at NULL)
verifications  (id PK, recipient_key, address, method, verified_at, evidence_hash)
claims         (id PK, recipient_key, payout_address, method, proposal_tx, status,
                challenge_ends_at, vetoed_at NULL)
jobs           (id PK, kind, payload, status, attempts, run_after, tx_hash NULL,
                last_error NULL, created_at, updated_at)
magic_links    (token_hash PK, email_key, address, expires_at, used_at NULL)
email_pending  (email_key PK, email_encrypted, first_notified_at, expires_at)
suppression    (email_key PK, created_at)          -- objections, kept to honour them
security_logs  (id PK, ip, user_agent, path, created_at)
```

| Data | Retention |
| --- | --- |
| Sender account | Life of the account; deleted 3 years after last activity, after a warning |
| Streams | Life of the account, or until stopped or lapsed plus 1 year |
| Onramp sessions | Life of the account; abandoned sessions deleted after 30 days. Stripe and the partner keep their own records |
| Pledges | Life of the account, or until the pledge has fully run or been cancelled plus 1 year |
| Recipient profile | While the recipient is opted in, or while pledges or an unclaimed allowance exist; refreshed from the platform at least monthly |
| Raw email of a designated recipient | Deleted right after the notification is sent, or after 30 days at most; only the HMAC remains |
| Magic links | Deleted 24 h after creation |
| Verifications and claims | Life of the recipient entry plus 1 year, for disputes |
| Jobs | 90 days after completion |
| Suppression list | As long as needed to honour the objection (HMAC only) |
| Security logs | 6 months |
| Backups | Expire within the shortest retention window they contain (§4.1) |
| OAuth tokens, KYC data, card data | Never stored by GoodStream |

### 11.4 People who haven't opted in (Art. 14)

Creators and email recipients can be designated without having used GoodStream, so until they opt in (§10.4):

- **Transparency.** Every public recipient page (`goodstream.in/<platform>/<id>`) and every notification email links to a privacy notice explaining what GoodStream holds, why, where it came from (the sender and the platform's public profile), and how to object.
- **One notification only.** A designated email gets at most one notification per 30 days, without the sender's identity unless the sender opts in. The raw address is then deleted.
- **Easy objection (Art. 21).** "I don't want GoodStream support" on the recipient page or in the email: the recipient record is flagged `opted_out`, its public page is removed, new pledges are refused, monthly-payment streams to them stop, and the guardian opens a refund so every sender can reclaim their share (§12.4). Email objections are stored in the suppression list as an HMAC only.

Once a recipient opts in, they're a GoodStream user and this section no longer applies to them; leaving works as described in §10.4.4.

### 11.5 Data subject rights

| Right | Implementation |
| --- | --- |
| Access and portability (Art. 15, 20) | "Download my data" in settings: JSON export of every row about the user, plus their on-chain addresses, pledge IDs and payout transactions |
| Rectification (Art. 16) | Profile data refreshed from the platform; email editable |
| Erasure (Art. 17) | Off-chain rows deleted. For recipients, the `recipientKey ↔ identity` row is deleted, leaving the on-chain key unlinkable. Wallet addresses and transactions already on-chain can't be erased; the privacy notice says so before any on-chain action |
| Objection (Art. 21) | §11.4 |
| Restriction (Art. 18) | `opted_out_at` also freezes processing during a dispute |

Requests are handled within one month (Art. 12). An erased recipient with an unclaimed allowance is warned first, because once the link is deleted they can't claim it anymore; the allowance then goes back to senders through the refund path.

### 11.6 Processors, transfers and security

- **Processors** with a data processing agreement (Art. 28): Infomaniak (VPS and backup storage, Switzerland), email delivery, error monitoring (with IP and personal data scrubbing). **Independent controllers:** Stripe and, once signed, the partner CASP for the onramp (including KYC and payment data), Google, Twitch and Meta for OAuth. A data-sharing agreement with the partner covers what GoodStream passes to it.
- **International transfers:** Switzerland benefits from an EU adequacy decision, so hosting at Infomaniak needs no extra transfer mechanism. For any other provider, prefer EU hosting; otherwise rely on the EU–US Data Privacy Framework or standard contractual clauses (Chapter V).
- **Security (Art. 32):** TLS everywhere, full-disk or volume encryption on the VPS, encrypted backups, `email_encrypted` with the data encryption key (§4.2), SSH key-only access with a firewall, unattended security updates, audit logs of support and admin access.
- **Breaches (Art. 33–34):** an incident procedure with notification to the [CNIL](https://www.cnil.fr/) within 72 hours when required, and to the people affected when the risk is high.
- **Cookies:** only strictly necessary cookies (session); no analytics or advertising trackers without prior consent, following CNIL guidance.
- **DPO:** probably not mandatory at GoodStream's size; name a privacy contact and reassess as the service grows.

## 12. Security and risk

### 12.1 Trust model

GoodStream's attester is a trusted party: if it is compromised, it can propose a wrong wallet. The limits on that:

- the escrow only accepts proposals from the current attester, which the guardian can rotate;
- every proposal waits 48 h before it takes effect, and the guardian can veto it until then;
- every proposal is a public `PayoutProposed` event, auditable on [Etherscan](https://etherscan.io/);
- the attester only proposes after a recorded verification event and is rate-limited (e.g. alert on more than N proposals per hour). It lives in the secrets file (§4.2) rather than a KMS, which the challenge window and rotation are designed to compensate for.

Because GoodStream pays recipient-side gas permanently (§9.3), the relayer is protected against being drained: at most one relayed payout per recipient every 7 days, only when the amount is worth at least 20 times the gas, a daily gas budget with alerts, and a small float topped up manually. `payout()` stays public, so anyone else can still pay the gas to trigger a payout.

Nobody needs to trigger monthly releases: what's due is computed on-chain from each pledge's start time and the schedule the sender signed. `payout()` is public but can only send to the payout wallet; `withdraw()` can only be called by that wallet. If the server stops, money still becomes due and can still be collected.

Senders don't trust GoodStream with their funds: their ETH sits in their own w3pk account until they pledge it, pledged ETH sits in a contract with no admin withdrawal path, and senders can cancel any time. With monthly payments, at most one month is ever in the escrow at a time. `fundFor` lets anyone pay for a pledge but gives the payer no rights: a partner, or anyone else, can only add money to a pledge owned by the sender's address. Sending pledges to a recipient this way costs the caller real ETH, so spam isn't free. GoodStream holds no ETH stock and no hot wallet beyond the relayer and attester, which only pay gas; its treasury Safe holds only support it received.

### 12.2 Contracts

Non-upgradeable escrow, no admin withdrawal path; funds only ever go to the recipient (`payout`, `withdraw`), back to the sender on `cancel`, or to senders on `reclaim`. External audit before mainnet beyond a capped beta. Fuzz the accounting invariant (§9.1) across `fund`, `fundFor` (with payer and owner different), `topUp`, `cancel`, `payout`, `withdraw` and `reclaim`, including settlements that catch up several months, many one-month pledges per recipient (monthly payments), payout proposals on keys with no pledges yet (self-registration), and proposals that take effect inside `payout`, `withdraw`, `proposePayout` and `openRefund`, and test re-entrancy on every ETH transfer.

### 12.3 Account edge cases

| Case | Handling |
| --- | --- |
| Sender loses their passkey | Recovery through w3pk's backup and recovery. Without recovery, the account's ETH and its pledges' cancel rights are lost: say so during onboarding |
| Sender misses a monthly payment | Reminders on the date and 3 days after; the stream lapses after 7 days. Nothing is lost, and resuming starts a new one-month pledge |
| Sender's card fails or Stripe declines a monthly payment | Same as a missed payment; the reminder offers another card, Apple Pay or Google Pay, or the own-ETH path |
| Sender sends ETH on the wrong network or the wrong token | Not detected by the app and not recoverable by GoodStream; the own-ETH screen warns about this before showing the address |
| Recipient loses their passkey | Recovery through w3pk's backup and recovery. A recipient who wants to move to a new wallet goes through a new verification and payout proposal with a fresh window |
| Instagram username changed | Not handled in v1 (§7.3) |
| Channel sold or account hacked | The escrow pays whoever controls the account at claim time; this is stated in the terms. The guardian can veto during the challenge window if a dispute is reported |
| Recipient refuses the money | Before opting in: objection (§11.4), then refund to senders. After opting in: opt-out (§10.4.4) |
| GoodStream's database is lost | Random keys can't be recomputed: keep encrypted, tested backups (§4.1). Pledges and allowances are on-chain, so senders can still cancel, and unclaimed allowances can still be refunded (§12.4) |
| VPS down | Funds safe; months keep becoming due on-chain; proposals, relayed payouts and reminders resume when it's back, and recipients with a payout wallet can call `withdraw` directly (§4.1) |

### 12.4 Unclaimed funds and refunds

If a recipient key still has no payout wallet in effect after **12 months** (the recipient never opted in), or its recipient objects, the guardian calls `openRefund(key)`. From then on, new pledges and settlements for that key stop, and anyone can call `reclaim(pledgeId)` to send each sender back both the unsettled part and the part already settled into the unclaimed allowance. Because no payout was ever set, nothing was paid out, and the escrow knows each pledge's contribution exactly: no Merkle root or off-chain computation is needed. The app warns senders after 30 and 90 days without a claim, and doesn't remind monthly-payment senders to keep paying a recipient who hasn't opted in after 90 days without asking them first.

## 13. Legal and platform prerequisites

*This list isn't legal advice.* Settle these before launch:

- **Name.** The product is GoodStream, at goodstream.in. The domain doesn't settle trademark rights: "GoodStream" is also used by goodstream.net (a creator live-streaming platform, a close field), goodstream.ai and goodstream.com. Run a trademark search (INPI, EUIPO) and consider filing before the public launch.
- **MiCA perimeter.** Get a short legal opinion confirming that GoodStream, as non-custodial software integrating Stripe's onramp and accepting ETH senders already own, isn't a CASP. The open points are the attester, which by deciding which wallet an escrow entry pays could be argued to provide transfer services on behalf of others, and the escrow itself, which holds pledged ETH under rules GoodStream wrote.
- **Stripe onramp approval.** Apply through the Stripe Dashboard before building the card path. During the application, ask which Stripe entity and MiCA licence serve EU buyers, get the EU fee schedule (it sets the monthly-payment threshold, §10.2.1), and ask whether onramp purchases can be made off-session for returning customers (§10.1.1).
- **Partner CASP due diligence (§10.8).** Check the MiCA authorisation and French passport on ESMA's register, and confirm the partner is merchant of record with its own acquiring. Include in the legal opinion that GoodStream, by passing amounts and dates to the partner, isn't collecting funds or acting as a payment agent. Have the partner's compliance team confirm that delivering to the escrow with `fundFor` fits its licence and its Travel Rule process. Settle chargebacks, SEPA returns and data sharing in the contract.
- **VAT and accounting.** No VAT for GoodStream on its service, since it charges no fee. Confirm with an accountant that voluntary support transfers fall outside the scope of VAT (§2), and how received ETH is booked and taxed as income. A real GoodStream fee would be taxable: TVA at 20% for French consumers, with place-of-supply rules for others.
- **GDPR deliverables.** Privacy notice, processing register, legitimate interest assessments, DPIA, processor agreements (including Infomaniak), breach procedure (§11).
- **Platform reviews.** Google OAuth verification for `youtube.readonly`, Meta app review for Instagram Login, Twitch app registration. Check each platform's developer terms on storing profile data.
- **Terms.** Self-custody of the sender's account, both funding paths (and that ETH sent on the wrong network is lost), ETH price exposure, pledge rules (monthly payments or budget, monthly amount, first month due immediately), monthly confirmations and lapsing, cancellation, recipient opt-in and opt-out, challenge window, refund policy, free relayed payouts and their limits, voluntary support, "pays whoever controls the account at claim time".

## 14. Milestones

| # | Milestone | Done when |
| --- | --- | --- |
| M0 | Prerequisites | Stripe onramp approval with EU fees, legal opinion on the MiCA perimeter, DPIA draft, trademark search for GoodStream, goodstream.in registered |
| M1 | Contract | `GoodStreamEscrow` deployed on Sepolia, Foundry tests passing (including invariant fuzzing and a mainnet fork) |
| M2 | Infrastructure | Infomaniak VPS provisioned for goodstream.in; `genji-web` and `genji-worker` under systemd; SQLite with WAL, Litestream backups and a tested restore; secrets file in place |
| M3 | Sender wallet | Genji + w3pk primary account receives ETH and sends escrow transactions, paying its own gas from the reserve |
| M4 | Fund | Amount calculator (§10.2) for both paths and both modes with live Stripe quotes and gas; **card**: embedded onramp in sandbox with signed webhooks for progress; **own ETH**: address, QR code and amount to send; account balance watcher for both |
| M5 | Pledge | Resolve, preview (with "On GoodStream" badge), pledge sized from available ETH, `fund` in one transaction, streams, sender dashboard (top up, change, stop, cancel) |
| M6 | Monthly payments | Reminder schedule, returning-customer checkout, one-month pledge per payment, lapsing and resuming |
| M7 | Recipients | Self-registration and opt-in at claim time, 4 verification methods, payout proposal, relayed `payout` with limits, recipient `withdraw`, support suggestion |
| M8 | Privacy | Privacy notice, data export, erasure, objection and opt-out flows, refunds, retention jobs |
| M9 | Beta | Audit, contract on mainnet (with `fundFor`), capped closed beta |
| M10 | Partner onramp | Partner CASP signed, `OnrampProvider` implementation in sandbox, automatic monthly payments delivered with `fundFor`, SEPA Direct Debit if offered, switch offered to existing Stripe monthly streams. Can run in parallel with M6–M9 |

## 15. Decisions and open questions

### 15.1 Decided (21 November 2026)

- **Name and domain.** GoodStream, at [goodstream.in](https://goodstream.in). No other domain is needed. A trademark search remains a prerequisite (§13).
- **Business model.** No fee. GoodStream suggests a voluntary "support GoodStream" transfer to creators when they collect (§10.4.3).
- **Other retail onramps.** None at launch. Ramp Network, MoonPay, Transak and Mercuryo all take 5% to 40% of a €10–20 payment, and none lets French buyers skip identification. Transak is the fallback if Stripe falls through (§10.7).
- **Partner CASP.** The target onramp: a MiCA-authorised seller with a near-zero spread, charging cards or SEPA mandates on its own account, with automatic monthly payments delivered by `fundFor` (§10.8). The contract includes `fundFor` from the start.
- **Monthly payments or budget.** Card streams above €10 a month are paid month by month, a few days before each month; smaller streams and own-ETH streams use an upfront budget, to keep Stripe's fixed costs low (§10.1.1, §10.2.1).
- **Recipient-side gas.** GoodStream pays it permanently, through its backend wallets (attester for proposals, relayer for payouts), with limits against abuse (§9.3, §12.1).
- **More identities.** X/Twitter, TikTok, Substack and domains (ERC-7529) come after v1 (§3).

### 15.2 Still open

- Real Stripe EU fees from live quotes, which set the monthly-payment threshold (€10 default) and the minimum budget.
- Whether Stripe can run onramp purchases off-session for returning customers, so that monthly payments need only the passkey approval (§10.1.1).
- Whether the own-ETH path should also let senders connect an external wallet (WalletConnect) and call `fund` from it directly, instead of transferring to their GoodStream wallet first. Cancel rights would then sit with that external address.
- Which partner CASP: shortlist from ESMA's register against the criteria in §10.8, and get quotes on spread, fixed fees, SEPA Direct Debit and eID support.
- Whether the partner can deliver with `fundFor` under its licence and the Travel Rule, or only to the sender's own account. In that case, each month would still need one passkey approval.
- Mercuryo's unpublished KYC threshold, and whether Transak's Simple KYC is allowed in any of GoodStream's target countries (`isLightKycAllowed`).

## Further reading

- [MiCA Article 3 definitions in ESMA's Interactive Single Rulebook](https://www.esma.europa.eu/publications-and-data/interactive-single-rulebook/mica/article-3-definitions)
- [Stripe embedded onramp overview](https://docs.stripe.com/crypto/onramp/embedded-overview)
- [Stripe EU KYC verification for the onramp](https://docs.stripe.com/crypto/onramp/eu-kyc-integration-guide)
- [Stripe onramp fee subsidization (US only)](https://docs.stripe.com/crypto/onramp/fee-subsidization)
- [Ramp Network fees for buying crypto](https://support.rampnetwork.com/en/articles/10415-what-fees-are-charged-when-buying-crypto)
- [Ramp Network KYC limits](https://support.rampnetwork.com/en/articles/441-what-are-the-kyc-limits-and-requirements)
- [MoonPay Europe pricing disclosure](https://www.moonpay.com/es/legal/europe_pricing_disclosure)
- [MoonPay verification tiers](https://dev.moonpay.com/platform/guides/verification-tiers)
- [Transak prices and fees](https://support.transak.com/en/articles/7845942-how-does-transak-calculate-prices-and-fees)
- [Transak KYC levels](https://docs.transak.com/guides/transak-different-kyc-levels)
- [Mercuryo crypto-asset pricing](https://help.mercuryo.io/hc/en-gb/articles/30404513537565)
- [Mercuryo KYC and compliance (widget docs)](https://widget.docs.mercuryo.io/guide/features/kyc)
- [Stripe card pricing for EEA businesses](https://support.stripe.com/questions/pricing-updates-for-businesses-based-in-the-european-economic-area-(eea))
- [AMLR requirements for CASPs, by Didit](https://didit.me/blog/amlr-crypto-casp-requirements/)
- [French DASP regime adjustments, by ADAN](https://adan.eu/en/publication/french-digital-assets-service-providers-dasp-regime-adjustments/)
- [w3pk live demo](https://w3pk.w3hc.org/)
- [SQLite write-ahead logging](https://www.sqlite.org/wal.html)
- [Litestream documentation](https://litestream.io/)
- [CJEU *Hedqvist* (C-264/14) explained by Norton Rose Fulbright](https://www.nortonrosefulbright.com/en/knowledge/publications/a0f1c5bb/bitcoins---ecj-rules-that-buying-and-selling-bitcoin-is-exempt-from-vat)
