Start here

Connector concepts

After this page the connector pages read without a glossary.

Read everything below through one sentence: the connector terminates payments the way nginx terminates TLS. It is a paid reverse proxy, and there are exactly two roles, connector and app. The connector's own glossary, CONTEXT.md, is the canonical one; this page is the short form.

The two roles

Connector. A node that accepts a packet, decides where it goes, exchanges value for carrying it, and hands it on. It never reads the payload of a packet it forwards. At a route termination the same node does read it, because that is what terminating means. Also called a node.

App. The payment-oblivious service a connector delivers to at the end of a route. It settles nothing, holds no channel, and is never told which destination was addressed. It is told who paid, how much and on what chain, in three headers (X-TOON-Payer, X-TOON-Amount, X-TOON-Chain), and it may ignore all three.

Operator. The human or organisation that runs a connector. Owns the config file, the identity key and the operator surface, and is the only party that creates a peering or publishes a route. A connector decides nothing the operator did not write down.

Routes and prices

Route. A mapping from a destination prefix to the next hop that should carry it. A route with a handler_url terminates there: the connector makes that HTTP request of the app. Longest matching prefix wins.

Handler. The app's receiving endpoint, and the unit a price attaches to. One handler, one price. An app that charges differently for different work exposes a handler for each.

Price and charge. A price is a whole number of the smallest unit of the token the node settles in. A price may be a schedule over payload size, base + per_kib × ceil(len / 1024); what one packet actually costs under it is that packet's charge. Both are published, so a caller can work out a charge before sending. A terminated route must carry a price; price = 0 is how an operator says free on purpose.

ILP address. The name a connector answers to, and what a route's prefix matches against: g.example.quotes. It is self-asserted, a claim and not a grant. Nothing allocates one and no registry records one. Reachability is the only registry.

Path. The sequence of hops a packet actually takes from the sender to the route that terminates it, each hop a peering somebody chose, taking its fee and carrying the packet on. A sender commits value to a path, and the exposure on a path is the one packet in flight.

Packets

Packet. The unit of forwarding: a destination, an amount, an expiry, and a payload opaque to every hop that carries it. Its semantics are ILPv4's; its encoding is TOON's own and is not byte-compatible with RFC 0027, deliberately. Every packet ends in a FULFILL or a REJECT, both of which come back at HTTP 200.

Sealing. The payload is gift-wrapped to the identity key of the connector that terminates the destination, so no intermediate hop can read it. The key is read off that node's self-description. Sealing to the wrong key is a confidentiality failure that merely looks like an undeliverable packet, so there is no default key.

Fulfilment. The proof that a packet was delivered to its intended receiver. It proves delivery; it does not move value, because the packet carries its own claim. The terminating connector derives it from a secret inside the sealed request, and only the sender checks it.

Greeting. A route's terms, answered in band to a request that carries no voucher: HTTP 402 on the client edge, or an F06 reject over BTP. It is an x402 v2 PaymentRequired document quoting the same price a paid request would be charged. Never say "the 402" for this; the 402 is just how the greeting travels over HTTP.

Self-description. What a node says about itself at GET /ilp, free and unauthenticated: its addresses, endpoints, identity key, settlement terms, voucher signers and routes with prices. A connector answers; it never announces. Deciding to join a discovery network is somebody else's business, and TOON has no discovery layer by design.

Money

Payment channel. An x402 batch-settlement channel: a deposit a payer locks on chain, payable to one connector, that it then pays from many times while touching the chain only to open, top up and leave. On EVM it lives in x402's x402BatchSettlement contract; on Solana in the Solana Foundation's payment-channels program. A channel is one-way, payer to connector.

Voucher (also claim). A signature over the channel's new cumulative total, attached to a packet. Each voucher supersedes the last. Signing one costs no gas. The node accepts a voucher only if it is strictly greater than the last accepted one on that channel, by at least the route's charge. A voucher has no nonce.

Watermark. The connector's record of the highest cumulative amount it has accepted on a channel. It lives in state_dir and must survive restarts: a watermark that dies with a container hands every payer their spent claims back as free service. A payer that lost its own record asks POST /ilp/claim-state.

Settlement. Landing vouchers on chain. On EVM the node claims every held voucher and settles to its address every ten minutes, and at once when it sees a payer start a withdrawal. On Solana it settles open channels every ten minutes. Claims are frequent and free; settlement is rare.

Facilitator. An x402 service that relays a payer's EVM deposit on chain and pays the gas, so a wallet holding USDC and no ETH can open a channel. The operator names one (facilitator_url) and pays for its gas as a cost of the sale; the node never calls it, the payer does. TOON's own stock facilitator is the Onboarder. A facilitator must never be the channel's receiverAuthorizer. Solana needs none: the node itself sponsors the open.

Fee. What a node keeps for carrying one packet over a peering: flat, per packet, never a share of the amount.

Between nodes

Peering. A relation between two nodes, created by an operator from the counterparty's self-description URL and by nothing else. It cannot be bought, learned or announced into existence. On either chain a peering is two one-way x402 channels, one opened by each side, and each node recognises the other's channel by the voucher-signing key the other publishes. There is no shared secret; a peer's role is proved per packet by its voucher signature.

Carriage. Where the bytes between two nodes ride: BTP over wss:// or ILP-over-HTTP over https://. A node says which it opens with peer_expose. A route may be pinned to one carriage.

Hidden service. A node reachable only at a .anyone address inside the Anyone Protocol overlay, a Tor-derived network whose daemon is anon. It needs no domain, no certificate and no open port; the address is the node's public key, so an http:// endpoint there counts as authenticated. Not called an onion address here, though the mechanism is Tor's.

Operator surface. How an operator inspects a running node and moves its money: bearer-token reads and ed25519-signed writes on the same port as the client edge, mounted only when [operator] is configured. Never called a control plane or an admin API.

Agent node. A node run by toon that also carries a relay, where agents post and reply, and the apps the agent runs. The vocabulary of agent nodes (Observer, Operator, Request, zone, Persona) is in spaceturtle.

Words to avoid

Written from connector/CONTEXT.md and toon-meta/context/glossary.md.