Receipt Attestation (EAS)

Signed receipts become an on-chain Usage Root through one EAS attestation per (epoch, subject_wallet, subject_epoch). The pattern comes from Dojang.

The pattern: Dojang’s Balance Root, applied to usage

Dojang (도장, the seal) is GIWA’s attestation system. One of its schema pairs is a ready-made template for proving private per-user numbers against a public commitment:

Balance Root: one attestation per (coinType, snapshotAt) carrying a Merkle root over all users’ balances at a snapshot.
Verified Balance: a per-user Merkle proof against that root, provable without revealing anyone else’s balance.

Tokscale applies the same commitment idiom to AI usage. The Usage Root mirrors the Balance Root; the per-receipt inclusion proof mirrors the Verified Balance. It is Dojang’s own design language, readable by anyone who already understands GIWA attestations. See Dojang: On-Chain Attestations.

The attestation: an eight-word data tuple

There is no global cross-builder root: the EAS recipient is the builder’s wallet, and wallet-bound leaves prove membership for that Passport only. The schema string is:

bytes32 receiptRoot,uint64 epoch,uint32 subjectEpoch,uint32 receiptCount,bytes32 summaryCommitment,bytes32 dojangAttesterId,bytes32 dojangVerifiedAddressUid,uint16 schemaVersion

ABI-encoded, this is eight 32-byte words:

Field	Meaning
`receiptRoot`	Merkle root over the subject’s signed receipts this epoch
`epoch`	The gateway usage epoch
`subjectEpoch`	The builder’s own epoch counter (a wallet change starts a new subject epoch)
`receiptCount`	Number of leaves under the root
`summaryCommitment`	Salted commitment to the epoch’s totals (below)
`dojangAttesterId` / `dojangVerifiedAddressUid`	Optional Dojang context captured at publication; zero means no Dojang reference
`schemaVersion`	Schema evolution counter; any layout change registers a new schema UID and increments this

The attestation is non-revocable, has no resolver, and evolves only by new schema registration: EAS schema content participates in the schema UID, so a changed layout is a new schema, never an in-place upgrade.

Leaves, salt, and the provable tier

Membership leaves bind each receipt to one wallet and one subject epoch:

leafDomain = keccak256("TOKSCALE_RECEIPT_LEAF_V1")
leaf       = keccak256(abi.encode(leafDomain, receiptDigest, subjectWallet, subjectEpoch))

Privacy comes from what stays off the chain. Per-request model and cost data never leaves the holder’s receipt payload. On-chain, the epoch’s totals sit behind a salted commitment:

summaryCommitment = 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. A builder who wants to disclose totals reveals them with the salt, and anyone can recompute the commitment. The uint8(1) discriminator is the gateway-observed-v1 protocol code: the class of evidence behind the root is committed on-chain, not asserted in copy. A tier-in-the-leaf design, leaf = hash(builderAddr, tokens, cost, tier, receiptRoot, salt), would make the verification tier part of the committed data so the tier itself is provable; the frozen V1 implementation instead carries that evidence class as the protocol discriminator inside summaryCommitment and keeps leaves minimal (digest, wallet, subject epoch). Either way, a verifier checks the class cryptographically rather than trusting a label. The five-tier vocabulary is defined in Verified Usage and the Evidence Ladder.

The attestation worker pipeline

The publisher is a background worker following the reconciler pattern: its own pool, an advisory lock, and exactly one replica publishing.

Check cryptographic eligibility

Before a receipt commitment can enter a candidate set, the worker recomputes the fixed V1 typed data and digest and verifies a canonical low-S ECDSA signature against the versioned production signer registry. The registry excludes the local Anvil fixture signer. A job state of issued, a 65-byte blob, or a digest-shaped value is never proof; a poisoned row yields no candidate.

Construct the root

Per (epoch, subject_wallet, subject_epoch), collect commitments, order leaves by raw RFC 4122 UUID bytes, and build the receiptRoot.

Persist the durable intent outbox

Write the intent before broadcast, keyed unique on (epoch, subject_wallet, subject_epoch, eas_schema_uid). A submit timeout is pending, never permission to issue a second attestation for the epoch.

Publish and reconcile

Broadcast one attest() call, retain the transaction nonce and hash, and reconcile the receipt and canonical block before recording the EAS UID.

Persist the proof

Store the attestation UID, transaction hash, root, leaf version, and the ordered leaves or proofs so the public proof page survives retention and project deletion.

The worker and its vector suite are covered by the three-language vectors described in UsageReceiptV1:

bun run attestation-vectors:verify
# runs: cargo test -p giwa-onchain --test attestation_vectors
#       bun attestation-vectors:verify (viem)
#       forge test --match-contract ReceiptAttestationV1Test

Next steps

For the receipt format that feeds the leaves, see UsageReceiptV1.
For the attestation rail this schema publishes onto, see Dojang: On-Chain Attestations.
To verify one receipt against a published root, see Verifying a Receipt.
For what is anchored on the public chain today, see Live Evidence.

Overview

Payment

Proof

Runtime

Reference

Receipt Attestation (EAS)

The pattern: Dojang’s Balance Root, applied to usage

The attestation: an eight-word data tuple

Leaves, salt, and the provable tier

The attestation worker pipeline

Next steps

​The pattern: Dojang’s Balance Root, applied to usage

​The attestation: an eight-word data tuple

​Leaves, salt, and the provable tier

​The attestation worker pipeline

​Next steps

The pattern: Dojang’s Balance Root, applied to usage

The attestation: an eight-word data tuple

Leaves, salt, and the provable tier

The attestation worker pipeline

Next steps