Table of contents
Evidence and identity
Attested
The top tier of the evidence ladder. Gateway-verified usage anchored on GIWA through EAS and bound to a Dojang identity. Anchoring lands only on the local EAS fixture today; zero Usage Roots exist on public GIWA Sepolia. See Verified Usage and the Evidence Ladder.Builder Passport
A Dojang-bound, non-transferable record of how a builder works with AI, assembled from verified usage, active days, per-harness skill signals, and verification rate. It is issued as EAS attestations about an address, never as a token owned by one. See Builder Passport.Consistency-checked
The second tier of the evidence ladder. Self-reported usage that passes Level 1 validation on submission. Stronger than raw self-report, still client-originated.Dojang
도장, the seal. GIWA’s attestation service, built on EAS at the OP Stack predeploy slots, which issues trusted off-chain facts as on-chain attestations with zero personally identifiable information on-chain. Its defining property is that identity lives as attestations about an address rather than as tokens owned by one, which makes its credentials non-transferable by construction. See Dojang: On-Chain Attestations.Dual identity
One Tokscale account joining a GitHub identity (the immutable numeric user ID) and one or more wallets (keyed by(chain_id, address)), where neither identity can be reassigned to another user. See Dual Identity.
Evidence ladder
The five verification tiers every Tokscale usage number carries, in ascending order: self-reported, consistency-checked, source-verified, gateway-verified, attested. Migrating usage up the tiers is the product’s growth engine. See Verified Usage and the Evidence Ladder.Gateway-verified
The fourth tier of the evidence ladder. Usage observed directly by the gateway as it proxies the request, bound to a project and a price, and written into the append-only request ledger. The gateway sees the traffic because it serves the traffic.Level 1 validation
The open-source project’s name for the checks a submission must pass before it is published: totals must reconcile, no negative values, no future dates, required fields present, and duplicates rejected. Usage that passes is consistency-checked. It catches accidents, not determined forgery, because the input still originates on the machine being measured.Proof of Actual Work
Tokscale’s framing for the whole loop: usage becomes proof, proof becomes identity, identity becomes income. See Manifesto.Self-reported
The bottom tier of the evidence ladder. Usage read off a developer’s own machine by the Tokscale CLI, which covers 41 client integrations. Real data that solves cold start, and forgeable by construction, so it is labeled as such everywhere it appears. See Supported Clients.Skill signal
Per-harness proficiency derived from verified usage: which agents a builder uses, at what intensity, and at which tier. A dedicated Skill Signal attestation schema is part of the planned Tokscale schema set and is not registered publicly yet.Source-verified
The third tier of the evidence ladder. Usage cross-checked against provider billing records. Labeled as a target: no page, badge, or receipt in the current system claims it.Subject epoch
A builder’s own epoch counter, distinct from the gateway usage epoch. A wallet change starts a new subject epoch, and existing commitments are never rewritten, so history stays attached to the wallet that earned it.Tokscale CLI
The open-source command-line tool that reads token usage from the coding agents installed on a machine, prices them against LiteLLM data, and optionally publishes the result to a public profile. Live today attokscale.ai, and distinct from the GIWA gateway this documentation describes. See The Open-Source Base.
Usage Root
One EAS attestation per(epoch, subject wallet, subject epoch) carrying the receiptRoot over that subject’s receipts. It mirrors Dojang’s Balance Root idiom: a public commitment with private per-user proofs. Publishing the first Usage Root on public GIWA Sepolia is a tracked milestone. See Receipt Attestation.
Verification rate
The share of a builder’s usage sitting at gateway-verified or attested rather than self-reported. Anyone can report usage; only gateway-observed usage raises the rate.Verified Address
A Dojang attestation with the schema textbool isVerified, proving that a wallet passed KYC with a Dojang issuer. Read on-chain through one DojangScroll.isVerified call. Gating Passport registration on it is a Phase 2 mechanism.
Payments and x402
Body-aware maximum quote
The ceiling the gateway computes before issuing a 402, derived from the request body’s canonical input-token upper bound and output-token cap priced against the sealed catalog price. It grows with each additional message, so a multi-message request settles well under its maximum.Epoch
The gateway usage window whose receipts fold into one Usage Root. One attestation covers every receipt in the epoch, so on-chain cost is constant in request count.ERC-3009
The transfer-with-authorization token standard the x402exact scheme settles against directly, with no proxy contract. Its signed value is fixed at signing time, which is why it cannot serve upto.
exact
The x402 scheme that settles one fixed amount. Tokscale uses it for Stage A credit top-ups over ERC-3009. Proven once on public GIWA Sepolia.
Facilitator
The service that verifies x402 payment signatures and broadcasts settlements. GIWA has none, so Tokscale self-hosts a digest-pinnedx402-rs image and operates the facilitator role itself. See x402 Payments on GIWA.
Permit2
Uniswap’s canonical approval contract, an OP Stack preinstall at0x000000000022D473030F116dDEE9F6B43aC78BA3. The upto scheme is Permit2-only in x402-rs, which is why Tokscale deployed the canonical Permit2 proxies to GIWA Sepolia.
Request binding
The record capturing every immutable request and chain fact for one payment: project, API key, protocol, route, request ID, fingerprint, maximum, expiry, network, asset, treasury, facilitator, and proxy. Its digest derives the signed Permit2 nonce, so a valid signature cannot be rewrapped for a different request or configuration.Settlement journal
The x402 adapter’s append-only record, written before its sole settlement side effect. A prepared record without a transaction hash means the adapter refuses to broadcast again and recovers read-only instead.Stage A
Credit top-up: oneexact ERC-3009 settlement converted into prepaid project credit by a reconciler that sends no transactions and credits only from canonical chain evidence. See x402 Stage A.
Stage B
Per-request settlement: authorize a signed maximum withupto, settle the actual measured usage. Proven on the local topology including fault recovery. See x402 Stage B.
tUSD
“Tokscale Test USD”, the ERC-20 test asset all x402 flows settle in. Six decimals mirroring USDC, an ERC-3009 subset, and a permissionless faucet. A test-only token, not a stablecoin.upto
The x402 scheme that authorizes a signed maximum and settles the actual amount. Implemented with Permit2 and a hardcoded proxy address in x402-rs.
x402
An open payment protocol that activates the HTTP402 Payment Required status code: the server answers an unpaid request with a machine-readable payment requirement, the client signs an authorization and retries, and a facilitator settles it on-chain. Governed by the x402 Foundation under the Linux Foundation, initiated by Coinbase. GIWA does not officially support it; Tokscale ported the stack.
Protocol and wire format
Tokscale Gateway
The EIP-712 domain name in every issued UsageReceiptV1, paired with the V1 merkle leaf and node domain separatorsTOKSCALE_RECEIPT_LEAF_V1 and TOKSCALE_RECEIPT_NODE_V1. All three are hashed into issued signatures and proofs, so a verifier selects them from a receipt’s persisted schema version. See UsageReceiptV1.
tok_
The prefix on every project-scoped gateway API key. Keys are stored only as digests.
receiptRoot
The ordered Merkle root over one builder subject’s signed receipts in one epoch, built under the frozen leaf and node domains. It is the value carried in the Usage Root attestation.
signerVersion
The issued-envelope field naming the registered gateway key generation that signed a UsageReceiptV1. A verifier looks the envelope’s signerAddress up in the signer registry under this version, so the issuer key can rotate without changing the frozen V1 schema. It is distinct from receiptSchemaVersion, which is fixed at 1.
Summary commitment
The salted commitment to an epoch’s totals,keccak256(abi.encode(totalTokens, costUsd1e4, uint8(1), salt)). The salt stays server-side, so the public anchor reveals the root and the count but not the totals. The uint8(1) discriminator commits the evidence class on-chain rather than asserting it in copy.
tt_
The prefix on an API token issued by the open-source Tokscale CLI for publishing usage to a public profile. It is a separate namespace from the gateway’s tok_ project keys, and the two are never interchangeable.
UsageReceiptV1
The narrow EIP-712 typed-data statement the gateway signs after observing provider usage for one request and fixing the pricing snapshot. Off-chain, zero gas, verifiable with no Tokscale account. Field order, types, semantics, domain, and chain ID are immutable; any change creates a V2. See UsageReceiptV1.Networks and infrastructure
Chain ID 91342
The GIWA Sepolia chain ID,eip155:91342. The local Anvil stack borrows it deliberately so the frozen V1 wire format stays byte-identical, which means chain ID cannot be a network identity. See Network Separation.
EAS
Ethereum Attestation Service. On GIWA Sepolia it sits at the standard OP Stack predeploy slots, SchemaRegistry at0x4200000000000000000000000000000000000020 and EAS at 0x4200000000000000000000000000000000000021. Schema registration is permissionless.
Flashblocks
GIWA’s sub-second preconfirmation stream, roughly 200 milliseconds on the Flashblocks RPC. A user-experience primitive that makes per-request payment feel like a Web2 API call. Never finality, and never a credit trigger.GIWA Sepolia
The public GIWA testnet: an OP Stack L2 by Dunamu (Upbit), ETH gas, roughly one-second blocks, chain ID 91342. GIWA mainnet does not exist yet. See The Public Chain.GIWA_NETWORK
The declared per-deployment network enum, localnet or giwa-sepolia. Together with the immutable one-time database binding, it is the actual network boundary that chain ID cannot provide.
Localnet
The sealed, disposable Anvil topology that borrows chain ID 91342 and runs the full loop hermetically. Every key inside it is a publicly known Anvil development key. Local evidence never carries a Sepolia explorer link.Request ledger
The append-only table where every completed request lands as exactly one immutable row. ABEFORE UPDATE OR DELETE trigger raises giwa request ledger is append-only on any mutation, so history cannot be rewritten. It is the substrate receipts are signed from.
x402 adapter
The isolated process on port 8090 that owns everything x402-shaped. It exists because of a framework version mismatch between the workspace andx402-rs, and it is the only component that talks to the facilitator, the chain RPC, and the settlement journal.
Next steps
- New to the vocabulary? Start with Verified Usage and the Evidence Ladder, which introduces most of it in order.
- For what each term’s live status actually is, see Live Evidence.
- For the addresses behind the infrastructure terms, see The Public Chain.