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. With ETH they already own, it's seamless and costs nothing: no KYC, no fees, and GoodStream pays every network fee, so all of it reaches the creator. By card, Stripe's identity check and fees apply. 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.
1. Summary
GoodStream lets anyone support independent media and creators with a monthly ETH contribution:
-
Account. A sender signs in with a w3pk passkey. Their w3pk primary account is their wallet.
-
Fund. The sender puts ETH in that account in one of two ways:
- Pay by card. They buy ETH through the Stripe 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, and no gas: everything they send goes to the creator.
GoodStream never sells or holds ETH, and can't move it anywhere except to the chosen recipient, on the sender's schedule.
-
Pledge. From their account, the sender locks ETH in the
GoodStreamEscrowcontract on Ethereum 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. GoodStream pays the gas for every pledge transaction (§9.3), so the sender never needs ETH for fees. The pledge works the same whichever way the ETH arrived.
-
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).
-
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) |
1.2 Two kinds of sender
| Already holds ETH | Pays by card | |
|---|---|---|
| Identity check | None | Stripe's KYC on the first purchase: ID document and selfie for EU buyers (§10.1, step 4a) |
| Fees | None. GoodStream pays all gas, so every wei sent reaches the creator | Stripe's fees and spread, shown before checkout (§10.2) |
| Steps | Send ETH to the GoodStream wallet, approve the pledge | Stripe checkout (KYC once), wait for delivery, approve the pledge |
The own-ETH path is the seamless one, and the app treats it as a first-class choice: "Already have ETH?" sits next to "Pay by card" in step 2, and crypto users never see the Stripe widget. For card senders, the app reduces friction where it can: KYC happens once, the fee is shown before checkout, and budgets let a sender pay for several months in one purchase. The closed beta (M9) can start with ETH holders only, so real value flows before the card path is approved.
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. 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. - Gas sponsorship. GoodStream pays network fees for senders' escrow calls through a paymaster (§9.3). It pays gas from its own money and never receives, holds or moves the sender's ETH: the value of each pledge still comes from the sender's own account, in a transaction they approved.
- 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, sender transactions with gas paid by GoodStream (paymaster, §9.3), 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 or DNSSEC).
4. Stack
| Layer | Choice |
|---|---|
| Domain | goodstream.in (the only domain GoodStream needs) |
| App base | Genji — Next.js, Chakra UI, ethers v6, WCAG 2.1 AA, GPL-3.0 |
| Signer and sender wallet | w3pk passkey wallet, primary account (shipped with Genji); SIWE for backend sessions |
| Chain | Ethereum mainnet (chain ID 1); Sepolia for testing |
| Token | Native ETH (no wrapping) |
| Escrow | GoodStreamEscrow, GoodStream's only contract (§9) |
| Onramp (card path) | Stripe embedded onramp, destination ETH on Ethereum, plus Stripe webhooks. ETH on Ethereum is offered to merchants in all Stripe countries and to buyers in the EU and US (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) |
| Gas sponsorship | ERC-4337 bundler and paymaster from a hosted provider, with a GoodStream sponsorship policy that only covers calls to GoodStreamEscrow (§9.3). No GoodStream contract to deploy; requests are forwarded by GoodStream's backend |
| Hosting | One Infomaniak 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, one file on the VPS |
| Contracts | Solidity, Foundry |
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
jobstable in SQLite. The worker claims a job withUPDATE … RETURNINGinsideBEGIN 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 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
200quickly. 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 callwithdraw(), 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, mode600), passed to the services with systemdLoadCredential(orEnvironmentFile). They are never committed and never logged. - An encrypted copy (e.g. with 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). The paymaster provider's API key sits in the same file; its sponsorship balance is topped up from the treasury too.
- 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 no gas for escrow calls (§9.3). |
| 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. |
| Paymaster | Hosted ERC-4337 paymaster that pays the gas for senders' fund, topUp and cancel calls, under GoodStream's sponsorship policy and from GoodStream's prepaid balance (§9.3). Never touches the sender's ETH. |
| Treasury | GoodStream's own Safe. Receives voluntary support transfers (§10.4.3) and tops up the relayer and attester gas floats and the paymaster balance. 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 signed by the primary account after a passkey approval. w3pk's primary account submits transactions through a bundler, so each action is an ERC-4337 user operation. For escrow calls (
fund,topUp,cancel), GoodStream's paymaster pays the gas (§9.3): the account only needs the ETH it pledges, and no gas reserve is ever added to a purchase or transfer. Sending leftover ETH elsewhere is the one action GoodStream doesn't sponsor: its gas is taken from the amount sent. - If the paymaster is unavailable or a sponsorship limit is reached (§12.1), the app says so and offers to pay the gas from the account's own ETH, with the cost shown first. GoodStream stays a convenience, not a gatekeeper.
- 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:
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 channels.list (forHandle / id) with an API key |
twitch | Numeric user ID | twitch.tv/<login> | Twitch 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.readonlyis 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 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 (auth code), no extra scope | GET /helix/users with the user token returns the user ID behind the recipient key |
| 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)locksmonthly × monthswei 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 tosender: onlysendercan top up or cancel it, and refunds go tosender. 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. AFundedForevent 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: bypayout,withdraw,cancelortopUp. Settling late catches up every missed month; nothing can ever be settled early or beyond what the sender locked. topUpadds months to a pledge that still has months to come.cancelsettles 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 canvetoit. No separate finalize transaction is needed: the firstpayoutorwithdrawafter the window records it. Themethodcode (1YouTube,2Twitch,3Instagram,4email) 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 toto. 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, andreclaim(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.
// 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 are paid by GoodStream.
fund,topUpandcancelare sent from the sender's own account as user operations, and a hosted ERC-4337 paymaster pays their gas from GoodStream's prepaid balance. A monthly-payment stream costs GoodStream onefundper month; a budget stream costs onefundin total, plus anytopUporcancel. - Sponsorship policy. Enforced by the provider's policy rules and by GoodStream's backend, which forwards every user operation:
- only calls to
GoodStreamEscrow, and onlyfund,topUpandcancel; plain transfers and other contracts are never sponsored; fundandtopUponly above the minimums of §10.2 (minEURfor a budget, one month aboveTfor a monthly payment), so GoodStream's gas stays under 10% of what reaches the creator;- per account, at most 10 sponsored operations a day; globally, a daily gas budget with alerts at 50% and 80%;
- above a base-fee ceiling, the app offers to wait for cheaper gas or to pay it from the account (§6).
- only calls to
- Partner CASP. The partner sends
fundForitself. The target is for it to bill that gas to GoodStream rather than add it to the sender's price (§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 relayedpayoutcalls. 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 callwithdrawthemselves pays their own gas. The contract takes no fee. - Cost. All gas, sender-side and recipient-side, is now GoodStream's main running cost. At a few cents to tens of cents per transaction, depending on the base fee, it scales with the number of pledges and is funded from the treasury, which voluntary support transfers feed (§10.4.3). The minimums of §10.2 keep it proportionate.
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:
Support @lemediaindé with €5/month
For the creator €20.00 (4 months: €5 now, then €5 each month)
Network fees €0.00 (paid by GoodStream)
Stripe fees €x.xx (card only, from Stripe's live quote; €0 with own ETH)
─────────────────────────────────
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:
Support @lemediaindé with €20/month
For the creator €20.00 / month (first month now)
Network fees €0.00 / month (paid by GoodStream)
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). 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: the pledge, nothing more, since GoodStream pays the gas (§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, no gas. 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, and "Network fee: paid by GoodStream". The sender approves with their passkey and the app sends one sponsored 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
topUpto 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.
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
fundandfundForneed the recipient key in their calldata, and the contract has noreceive(). 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
fundForwith 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 and pays all gas. Everything the sender pays goes to the recipient, plus Stripe's fees on the card path. With ETH they already own, the sender pays nothing on top of the pledge.
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 cost of the pledge transaction, in ETH, paid by GoodStream's paymaster. Used only for the minimums below, never charged to the sender | gasUnits × (baseFee + tip) × 1.3, with gasUnits measured on a mainnet fork for a sponsored fund user operation |
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
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) stay under 10% of the amount, and that GoodStream's gas G per payment stays under 10% too. 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)
amount charged EUR = M + A(M) + s × M # A = card or SEPA fee, s = partner spread
delivered partner calls fundFor{value: m}(senderAccount, key, m, 1)
gas billed to GoodStream (target, §10.8)
where A(M) ≈ 1.5% × M + €0.25 (standard EEA card) or ≈ €0.35 (SEPA Direct Debit)Monthly payments through Stripe (each month)
ETH needed E ≈ M / P
amount to pay EUR = Stripe quote S(E).total
pledge m = D, fund(key, m, 1) # D = ETH available for this payment; gas sponsoredBudget: before funding (estimate shown in step 2)
months N = floor(B / M) # budget rounded down to whole months
ETH needed E ≈ (N × M) / P # no gas reserve: GoodStream pays the gas
card: amount to pay EUR = Stripe quote S(E).total # includes Stripe fees and Stripe's delivery gas
own ETH: amount to send E − (ETH already in the account) # no fees of any kindBudget: after delivery (exact, shown in step 6)
available D = ETH in the account for this pledge (delivered by Stripe, sent in, or already there)
pledge E_p = D # all of it: gas is sponsored
monthly (wei) m = floor(E_p / N)
locked m × N # rounding dust stays in the sender's accountThe 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 (always €0.00, "paid by GoodStream"), 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, GoodStream's gas and, for the card path, Stripe's network fee are fixed costs per pledge, so the app enforces a minimum budget where each stays under 10% of the total: minEUR = max(€20, G_EUR / 0.10, StripeNetworkFee_EUR / 0.10) for card and max(€20, G_EUR / 0.10) for own ETH, recomputed hourly from gas prices. The paymaster refuses to sponsor pledges below it (§9.3). 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. GoodStream pays all gas: senders' escrow calls through the paymaster, payout proposals through the attester, and relayed payouts through the relayer (§9.3). A recipient can always call withdraw and pay their own gas instead.
Examples (illustrative only: plug in live values). Own ETH: a sender who pledges 0.01 ETH sends exactly 0.01 ETH, and all of it goes to the creator. 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 user operation from the sender's primary account, approved with their passkey, with gas paid by GoodStream's paymaster (§9.3), whichever way the ETH arrived:
escrow.fund{value: m × N}(recipientKey, m, N) # N = 1 for each monthly paymentAfter 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:
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 audienceBecause 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:
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
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" suggestionEach 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, or the paymaster's prepaid balance, falls below a few days of expected use; reports the day's sponsored gas against the daily budget (§9.3) |
| 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) | To ask during the application (§13) |
| Ramp Network | 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) | Ramp Swaps (Ireland), MiCA CASP, listed by the AMF for France since 2 December 2025 |
| MoonPay | 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) | MiCA licence in the Netherlands |
| Transak | 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). 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 | 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). 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). 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).
- 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), 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
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 + A(M) + s × M (§10.2): the card or SEPA fee A and the partner's spread s. The gas for fundFor is billed to GoodStream, monthly, as part of the contract (to negotiate). 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).
- 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.
fundForships in the first contract.- The backend talks to onramps through one
OnrampProviderinterface. 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 principles of data protection by design and by default (Art. 25) and the EDPB's Guidelines 02/2025 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):
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), the bundler and paymaster provider (receives user operations, which contain only on-chain data; GoodStream's backend forwards them, so the provider never sees senders' IP addresses). 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_encryptedwith 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 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
PayoutProposedevent, auditable on Etherscan; - 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.
GoodStream also pays senders' gas (§9.3), so the paymaster is protected the same way: it only sponsors fund, topUp and cancel on GoodStreamEscrow, only above the minimum amounts, at most 10 operations per account a day, within a global daily budget with alerts. Draining it would mean locking real ETH in pledges above the minimum, which caps GoodStream's gas at about 10% of the value pledged. If a limit is reached, the sender can still pay their own gas (§6).
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 |
| Paymaster unavailable, or a sponsorship limit reached | The app explains and offers to send the transaction with gas paid from the account, showing the cost first. Nothing is blocked (§6) |
| 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, accepting ETH senders already own and paying their gas through a paymaster, 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
fundForfits 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, network fees paid by GoodStream and their limits, 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 calls as user operations, with gas paid by the paymaster under the sponsorship policy (§9.3); fallback to self-paid gas works |
| M4 | Fund | Amount calculator (§10.2) for both paths and both modes with live Stripe quotes, no gas charged to the sender; 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. It can open with ETH holders only, before Stripe approval, so real ETH flows from the start (§1.2) |
| 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. 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 includesfundForfrom 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).
- Sender-side gas. GoodStream pays it too, through a hosted ERC-4337 paymaster restricted to
fund,topUpandcancelon the escrow, with minimum amounts and daily limits (§9.3, §12.1). Senders who already hold ETH pay nothing at all; card senders pay only Stripe. - Two kinds of sender. The own-ETH path is seamless and free; the card path carries Stripe's KYC and fees. Both are first-class in the app, and the beta can start with ETH holders (§1.2).
- More identities. X/Twitter, TikTok, Substack and domains (ERC-7529) come after v1 (§3).
15.2 Still open
- Which bundler and paymaster provider: EU hosting or DPF coverage, sponsorship-policy rules (target contract, selectors, per-account limits), and price. Confirm with w3pk how its primary account submits user operations and attaches paymaster data.
- 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
fundfrom 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
fundForunder 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
- Stripe embedded onramp overview
- Stripe EU KYC verification for the onramp
- Stripe onramp fee subsidization (US only)
- Ramp Network fees for buying crypto
- Ramp Network KYC limits
- MoonPay Europe pricing disclosure
- MoonPay verification tiers
- Transak prices and fees
- Transak KYC levels
- Mercuryo crypto-asset pricing
- Mercuryo KYC and compliance (widget docs)
- Stripe card pricing for EEA businesses
- AMLR requirements for CASPs, by Didit
- French DASP regime adjustments, by ADAN
- w3pk live demo
- SQLite write-ahead logging
- Litestream documentation
- CJEU Hedqvist (C-264/14) explained by Norton Rose Fulbright