Gateways
Nodes speak plain HTTP on their own ports and are busy keeping the chain. A gateway stands in front of them for the public. It holds a domain's certificate, so browsers connect over HTTPS, and it serves the pages people open: the wallet, the explorer, the file-verification page, the manuals and the downloads. Gateways are listed on the chain, so wallets can find another one when theirs fails.
What a gateway does
A gateway is a role set up by the ZooBC installer, a separate program from the node. It terminates TLS (the encryption behind HTTPS) and passes API requests under /api/v1/ to two back ends:
- first to an archival service, which holds deep, searchable history (explorer and archival nodes);
- then to a node, when the archival service answers with an empty 404, meaning it does not have that route.
New transactions therefore end up at a full node, because only a node has a pool of pending transactions. The answers are the chain's own data; the gateway only carries them. It adds its own cross-origin (CORS) headers, allowing GET, POST and OPTIONS and an X-API-Key header, cached for 600 seconds.
A gateway never makes blocks, which only registered nodes do, never holds anyone's key, and does not exchange currencies.
Registering a gateway
An owner lists a gateway with RegisterGateway (type 36). It records:
- the gateway's own key, written
ZBG_…; - its domain: 1 to 256 characters, only letters, digits, dots and hyphens;
- its URL, which must begin with
https://and be at most 1,024 bytes.
It locks a stake of 10 ZBC (1,000,000,000 atomic units) from the owner's account. The amount is the voted gateway_registration_cost, which starts at 10 ZBC on every chain and moves only by the seats' price votes.
Staying listed
A gateway proves that it is alive with GatewayHeartbeat transactions (type 37). Each heartbeat is a 132-byte body: the gateway key, the height and hash of a recent block, and a signature by the gateway key over the first 68 bytes. The block it names must be within 20 blocks of the tip, so a heartbeat cannot be prepared in advance.
The chain allows a heartbeat interval of 240 blocks plus a grace period of 480: a gateway silent for 720 blocks (3 hours) is set inactive, and its owner gets the stake back. An owner can also leave at any time with UnregisterGateway (type 38), which returns the stake too. Nothing is burned: the stake is a deposit, not a payment, and there is no subscription.
Anyone can list the gateways at GET /api/v1/registry/gateways. The route's answer differs in form depending on whether the archival service or the node gives it. When its gateway fails, the web wallet re-reads this list, with the relay and archival lists, and moves on. Each gateway can also have relays attached to it.
The testnet faucet
On testnet, whose coins have no value, the gateway also serves the faucet at /faucet/. Give it an address and it sends test ZBC. The payout halves as you draw: up to 100 ZBC on the first request, then 50, 25, 12.5 and so on, until a request would pay less than 1 ZBC; then nothing more comes until the weekly reset. What has been drawn is counted by address or by internet (IP) address, so many accounts behind one connection share one allowance. The faucet is the one place that takes an amount in decimal ZBC rather than atomic units.
It pays any supported address, not only ZBC_… ones: a Bitcoin, Ethereum or other foreign address works too, since those keys can control ZooBC accounts (keys and account types). Test coins cannot be swapped for mainnet ZBC, and nobody sells them (devnet, testnet and mainnet).