utuh

# Utuh

**A completeness layer for the Attestcoin Protocol, and undercollateralized credit built on it.**

_utuh_ — Indonesian: whole, intact, with nothing missing.

Any registry on this protocol can tell you what it holds. Ask one whether a borrower has ever been
liquidated and it can only answer with what someone chose to submit — and the borrower will not be
submitting that. Utuh bonds the claim that a set is all of them, and pays half the bond to anyone
who proves one event was left out.

Built for BUIDL CTC 2026 Fall on Creditcoin.

**Technical brief:** https://claude.ai/code/artifact/2caca05b-c659-463f-b5ca-28e207f95147

Deployed and verified on Creditcoin CC3 Testnet. **[The console is live at
utuh.vercel.app](https://utuh.vercel.app/)** — it reads the chain from your own
browser, lets anyone sweep Ethereum and break an incomplete claim, and lets a borrower be
underwritten end to end without cloning anything. `npm run web` runs the same page locally.

Building something else on Creditcoin that needs a sentence about events that did _not_ happen?
The registry is usable on its own — see **[docs/INTEGRATING.md](docs/INTEGRATING.md)**.

---

## The problem

The Attestcoin Protocol proves that a source-chain transaction _happened_. A Merkle proof places
the transaction in a block; a continuity proof anchors that block to an attestation stored on
Creditcoin. The Block Prover precompile at `0x0FD2` checks both natively, synchronously, inside a
single Creditcoin block.

What it cannot prove is that a _set_ of events is complete.

Whoever submits proofs chooses which proofs to submit. Every one of them verifies. Nothing in the
protocol notices the ones that were left out.

For credit, that gap is fatal. The sentence every on-chain credit system needs is:

> _This borrower has never been liquidated._

That is a statement about events which do not exist, and an inclusion proof can only ever speak
about events which do. A borrower assembles their own history, submits the flattering half, and
each proof checks out.

This is not hypothetical. Season 1 of this hackathon drew 76 submissions, and more than twenty of
them were some form of on-chain credit score or reputation-based lending; one of those, CreditX,
took a prize. Every one of them inherits this hole, the winner included — placing well is not the
same as closing it, and an inclusion proof gives none of them a way to.

## What this uses of Creditcoin's, and what it deliberately does not

`npm run doctor` ends by making a live request to every Creditcoin-owned surface this depends on,
so the list below is checkable rather than asserted. Today's run:

```
Creditcoin ecosystem surfaces
  ok    USC Oracle dashboard      200 — every verifyAndEmit here is listed by source height
  ok    testnet indexer           68,160 attestations of Ethereum, chain key 3
  ok    mainnet indexer           52,463 attestations of Ethereum, chain key 1
  ok    Creditcoin Mainnet RPC    chain id 102030
  ok    Blockscout · registry     UtuhRegistry verified
  ok    Sourcify · registry       chain 102031: match match, creation match
  ok    Blockscout · credit       UtuhCredit verified
  ok    Sourcify · credit         chain 102031: match match, creation match
```

On top of the protocol itself — both precompiles, both `verifyAndEmit` overloads, `EvmV1Decoder`,
`@gluwa/usc-contracts` and `@gluwa/usc-sdk`, the hosted Proof Builder under both of its hostnames,
and `RawProofBuilder` as the path that needs no hosted service at all.

Two of those lines are worth reading twice. Every append and every refutation goes through
`verifyAndEmit` rather than its `view` twin, so **Creditcoin's own oracle dashboard is the record**
— the network logged this project's work, not the other way round. And the **Creditcoin Mainnet**
indexer is read even though nothing here is deployed there: the console audits mainnet's attestors
against Ethereum itself, because auditing only the network you deployed to leaves the production
oracle unchecked by the one page that can check it.

### What is deliberately not integrated

PenguinBridge, PenguinSwap and PenguinBase are Creditcoin's own consumer applications and none of
them appears here. That is a design decision, not an oversight:

- **A bridge would contradict the product.** The whole claim is that nothing bridges — history
  stays on Ethereum, credit is issued on Creditcoin, and only proof crosses. Wiring a bridge in
  would make the pitch untrue.
- **A DEX price would reintroduce the oracle.** Crossing from a source asset to CTC is a price,
  and the lender states its own rate on-chain precisely so the protocol never pretends to know
  one. Reading a swap rate would replace a stated assumption with a hidden one.

An integration that weakens the thesis is not depth. Naming the two we refused is more honest than
listing eleven we bolted on.

## Where this sits next to Creditcoin's own example

Creditcoin ships a [loan-flow tutorial](https://github.com/gluwa/attestcoin-protocol-examples/tree/main/loan)
— `ASCLoanManager` on Creditcoin, an auxiliary contract on Sepolia, an offchain worker between
them. (Mid-season, gluwa reorganised that repo and began renaming USC to ASC — Attestcoin Smart
Contracts; the old `USCLoanManager` link now redirects to a 404, and everything below was re-read
against the renamed sources on 2026-09-04. The mechanics are unchanged.) It is a good tutorial and
it is the right shape for what it teaches. It is also a precise illustration of the gap, because it
is the reference every builder will start from.

Each event proves itself as it happens. `_markLoanAsFunded` and `_noteLoanRepayment` take one
proven transaction each; `ASCBase.execute` verifies it through `0x0FD2` and records the query so
it cannot be replayed. Every _present_ fact is cryptographic, and that part is sound.

Two things follow from proving one event at a time, and neither is a defect in the tutorial:

- Nothing asks whether the set is complete. That is fine when the loan is already registered on
  chain and the contract knows exactly which events it is waiting for. It stops being fine the
  moment the question is _"has this borrower ever been liquidated"_ — because that question is
  about events nobody submitted, and no number of inclusion proofs answers it.
- Default is declared, not proven. `markLoanAsExpired` is `onlyOwner`. Somebody trusted says the
  loan went bad. For a tutorial that is the honest simplification; for underwriting a stranger it
  is the whole problem moved one layer up.

Utuh is the layer that would sit under such a contract: a bonded claim that a set of events is
_all_ of them, refutable by anyone with one proof of one omitted event. Presence stays
cryptographic exactly as above. Absence becomes economic, which is the most that can be had.

## What Utuh does

Two halves, each sound on its own.

**Nothing invented.** Every event enters a claim through `appendBatch`, which runs the Attestcoin
Block Prover on it before it is recorded. Members must arrive in strictly ascending
`(blockHeight, txIndex, logIndex)` order, which the contract enforces rather than trusts. A claim
can only ever contain events that provably happened, so its aggregate cannot be inflated.

**Nothing omitted.** The claimant bonds the assertion that the set is complete. Anyone may break
the claim by proving a single in-scope event the set does not contain. Absence is never proven — a
claim of absence is _refuted by presence_, which Attestcoin does prove.

```
presence  →  cryptographic   (Merkle + continuity, verified by 0x0FD2)
absence   →  economic        (bonded assertion, refutable by one proof)
```

### What scales, and what does not

_Settling_ a claim is O(1): the registry never verifies a whole set, so a claim spanning ten
thousand events is broken by a single proof or by none at all.

_Building_ one is not. `npm run gas` measures it rather than reasoning about it — it finds every
transaction a registry has ever seen from the registry's own logs, reads the receipts, and fits a
cost model. No explorer involved. Across the four registries deployed so far, 139 transactions:

| Call                      | Gas (mean) | % of a 75M block |
| ------------------------- | ---------- | ---------------- |
| `open`                    | 252,750    | 0.33%            |
| `seal`                    | 206,010    | 0.27%            |
| `appendBatch` (1 event)   | 552,956    | 0.73%            |
| `appendBatch` (2 events)  | 893,903    | 1.19%            |
| `appendBatch` (10 events) | 2,662,045  | 3.54%            |
| `refute`                  | 611,556    | 0.81%            |
| `finalize`                | 209,258    | 0.27%            |
| `withdraw`                | 205,870    | 0.27%            |

Member count alone does not explain those. One append of **three** events cost 541,464 gas while
an append of **two** cost 878,903, because the cost follows the _size of the transactions being
proven_, not how many events sit inside them. A least-squares fit over all 56 appends the published
registries have seen, against the call's own calldata gas and its member count:

```
  290,899 gas fixed
    1.51 x the call's own calldata gas   (1.00 would be exact)
   81,427 gas per member on top of its bytes
  worst residual 294,878 gas, 32% of the mean append

each append carried median 94, 2..394 continuity hashes and median 16, 8..78 Merkle siblings
  charging the bytes at their own EVM price, 62 gas per continuity hash:
  5,866 gas at the median, 0.6% of the mean append
```

The calldata term is the solid one, and it is the interesting one: **a proven transaction costs
about twice its own calldata gas**, because those bytes are not merely paid for at the door — they
are copied, RLP-decoded by `EvmV1Decoder`, and hashed by the Block Prover. Proving one in-scope
log inside a fat mainnet transaction means carrying all thirty kilobytes of it, and that is not a
choice the claimant has.

The per-member t