Allows an AI agent to sweep bonded completeness claims on Creditcoin against Ethereum and refute claims that omit specific events.
Also known as PugarHuda/utuh, utuh, utuh-mcp
- Stars
- 0
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 0.4.0
- Last commit
- Nov 13, 2026
- License
- MIT
What is Utuh MCP?
Utuh allows an AI agent to sweep bonded completeness claims on Creditcoin against Ethereum and refute claims that omit specific events. It exposes 5 tools, such as tally, list_claims, sweep_claim.
Summary generated from the project's README
About Utuh MCP server
Utuh watcher provides a completeness layer for the Attestcoin Protocol, specifically designed to address gaps in event sets. While standard protocols can prove a transaction occurred, they cannot prove that a set of events is complete. This server allows an AI agent to act as a watcher that sweeps bonded completeness claims on Creditcoin against Ethereum history to identify and refute claims that omit specific events.
Developers can deploy the server locally using the npx command or connect to a remote instance via a hosted API. The system works by bonding claims; if an agent proves an event was left out, half of the bond is paid to the refuter. This tool is essential for developers building on-chain credit systems where verifying a borrower has never been liquidated is a critical requirement. It utilizes Creditcoin CC3 Testnet and interacts with Ethereum mainnet and Sepolia data to ensure the integrity of submitted histories.
What you can do with it
- 1Refute incomplete credit claimsAn AI agent can identify if a borrower has omitted liquidation events from their submitted history to claim a better credit score.
- 2Verify protocol integrityUsers can run a local judge command to re-measure all repository numbers against the live chain to ensure data consistency.
Written from the project's README. Every use case is checked against a quote from it.
How to install Utuh MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Utuh MCP in Claude Code
$ claude mcp add --env 'PRIVATE_KEY=<YOUR_PRIVATE_KEY>' utuh -- npx -y utuh-mcpInstall Utuh MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"utuh": {
"command": "npx",
"args": [
"-y",
"utuh-mcp"
],
"env": {
"PRIVATE_KEY": "<YOUR_PRIVATE_KEY>"
}
}
}
}Install Utuh MCP in VS Code
.vscode/mcp.json
{
"servers": {
"utuh": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"utuh-mcp"
],
"env": {
"PRIVATE_KEY": "<YOUR_PRIVATE_KEY>"
}
}
}
}Install Utuh MCP in VS Code CLI
$ code --add-mcp '{"name":"utuh","type":"stdio","command":"npx","args":["-y","utuh-mcp"],"env":{"PRIVATE_KEY":"<YOUR_PRIVATE_KEY>"}}'Install Utuh MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"utuh": {
"command": "npx",
"args": [
"-y",
"utuh-mcp"
],
"env": {
"PRIVATE_KEY": "<YOUR_PRIVATE_KEY>"
}
}
}
}Install Utuh MCP in Codex
$ codex mcp add utuh --env 'PRIVATE_KEY=<YOUR_PRIVATE_KEY>' -- npx -y utuh-mcpInstall Utuh MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.utuh] command = "npx" args = ["-y", "utuh-mcp"] [mcp_servers.utuh.env] PRIVATE_KEY = "<YOUR_PRIVATE_KEY>"
Install Utuh MCP in Gemini CLI
$ gemini mcp add -s user -e 'PRIVATE_KEY=<YOUR_PRIVATE_KEY>' utuh npx -- -y utuh-mcpInstall Utuh MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"utuh": {
"command": "npx",
"args": [
"-y",
"utuh-mcp"
],
"env": {
"PRIVATE_KEY": "<YOUR_PRIVATE_KEY>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for utuh-mcp 0.4.0 in an isolated container with no network and no keys. It answered and listed 5 tools.
Utuh MCP tools 5
Read from the server with tools/listtallyRead-onlyThe four numbers across both deployments: events proven into claims, claims sealed, claims broken by a refutation, and bond slashed. Read live from Creditcoin CC3 Testnet.
list_claimsRead-onlyA page of claims on a deployment, by id, each with its status, member count, bond, and — for sealed ones — how many Creditcoin blocks remain in the challenge window. Sealed claims inside their window are the ones a watcher can still act on. Pass the returned nextCursor to get the next page; utuh://claims/{deployment} is the same list in one read.
sweep_claimRead-onlySweep the source chain across independent endpoints for every in-scope event in a claim's range, take the union, and check each event against the claim on-chain. Needs no key and spends nothing. Reports complete with provenance, or the omitted event — which refute_claim can then prove, if the claim is still inside its window. Finalized and refuted claims can be swept too, for the record; open ones are still being built and cannot.
refute_claimActionProve one omitted in-scope event through the Block Prover precompile and break the claim. Sends a real transaction on Creditcoin CC3 Testnet and pays the caller half the bond. Requires PRIVATE_KEY in the environment with a little CTC for gas. Answers with sent: false and a reason whenever it did not send.
audit_attestorsRead-onlyAsk both Creditcoin networks (CC3 Testnet and Creditcoin Mainnet) what header hashes their attestors signed for recent Ethereum blocks, then check each three ways: against independent Ethereum endpoints, against that network's own ChainInfo digest index, and against the other network. A MISMATCH would mean attestors signed a block Ethereum does not have; NOT ON CHAIN would mean the indexer published an attestation the chain does not hold.
Configuration
PRIVATE_KEYSecretA funded Creditcoin CC3 Testnet key, needed only by refute_claim — which also demands confirm: true. Every other tool reads the chain and spends nothing.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubUtuh
Utuh bonds the claim that a set of events is complete, pays half the bond to anyone who proves one event was left out, and lends CTC undercollateralized against the claims that survive.
utuh — Indonesian: whole, intact, with nothing missing. A completeness layer for the Attestcoin Protocol, built for BUIDL CTC 2026 Fall and deployed on Creditcoin CC3 Testnet.
- Live: utuh.vercel.app (landing, read from Creditcoin as it draws) and the console at utuh.vercel.app/app/ (sweep, refute, borrow; no server, no clone).
- Two refuted claims, one click each: claim 5, sealed one event short and broken from a browser · claim 20, a false "never liquidated" over 216,000 Ethereum mainnet blocks, refuted by one liquidation proof
![]() |
![]() |
| The landing page, claim 5 as a working paper | The console, claim 20 opened verdict first |
![]() |
![]() |
| Dark scheme | A sweep of claim 5 from the browser, with its provenance |
- Verify every number yourself:
npm run judge— no key. It re-measures every number this repository and the submission quote against the live chain and exits non-zero on any that no longer holds. On 2026-09-14, after the production deploy, it printed 25 of 25, two of them checks that read the example gate below. - Hold the watcher role from an agent:
npx -y utuh-mcp— 0.4.0 on npm and in the official MCP Registry. For clients that cannot run a command, the same server answers athttps://utuh.vercel.app/api/mcp(below). - Measured: 211 Foundry tests with 16 invariants, 100% line and branch coverage and 99.1% of 737
mutants killed · Slither 0 findings · halmos 5 of 5 · every contract verified on Blockscout and matched on Sourcify · 248
TransactionVerifiedevents on CC3's own indexer. - Demo video (3 min): https://youtu.be/HwSnv3E4tzo · Whitepaper: PDF, from
web/whitepaper.html· Deck:web/deck.pdf
What is on-chain, all verified on Blockscout and Sourcify (every address and read):
| On CC3 Testnet (chain 102031) | Address | What it holds |
|---|---|---|
UtuhRegistry, Ethereum-mainnet-sourced |
0x8FA0…5Fac |
72 claims over real Ethereum mainnet history; 32 refuted, claim 20 among them |
UtuhRegistry, Sepolia-sourced |
0x2688…347b |
13 claims, the completed borrow-and-repay loop; claims 3 and 5 refuted |
UtuhCredit, Sepolia-sourced |
0x0177…24b6 |
lines 1–3 opened, drawn, repaid on Sepolia and settled; lines 2 and 3 entirely from the console |
SettlementLedger, on Sepolia |
0xC8C9…575B |
the source-chain repayments those lines settled on |
| Creditcoin's own oracle record | transaction-verifications | 248 TransactionVerified rows are Utuh's: 212 claim members, 34 refutations, the rest control bindings |
A contract that is not Utuh reads it: NeverLiquidatedGate
at 0xcA62…5D09
granted an allowance on claim 72
and refused refuted claim 20.
This project wrote and deployed it as the worked example, so it is not an outside user.
Contents
The short version · The problem · What this uses of Creditcoin's · Next to Creditcoin's own example · What Utuh does · Built on Ethereum mainnet · UtuhCredit · Deployed on CC3 Testnet · Two demonstrations · The watcher as an MCP server · The console · Layout · Running it · On testing · What the tools say · Before you build on this · Attestcoin surface used · Known limits · License
Elsewhere: docs/INTEGRATING.md (use the registry from your own contract) · docs/COMPLETENESS.md (does what you built have this gap?) · docs/ROADMAP.md (what is gated on whom) · docs/AUDIT.md · docs/MAINNET.md · SECURITY.md · 한국어 요약: docs/README.ko.md
The short version
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.
The landing page reads both registries from Creditcoin as it draws — the two refuted claims with
their block-range strips, the tally (proven, sealed, broken, burned), the deployed addresses — and
each deep link above opens the console on the claim with its verdict first. The console 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 serves both locally.
Every verification behind the two refuted claims is on Creditcoin's own oracle dashboard, which
nobody here can write to.
Two things a reader with a clone and no key can check first. npm run judge re-measures every
number this repository and the submission quote — the contracts and their verification, the tally,
both linked claims, the explorer counters, npm, the MCP Registry, the published build, the sixteen
protocol entry points, the test and commit counts — and exits non-zero on any that no longer
holds. And a bond here stands behind a specific line, not behind nothing: UtuhCredit.openLine
reaches a claim only through UtuhRegistry.isUsable(claimId, exposure), the finalized claim is
spent by the line it opens, underwrittenThrough consumes the history range, and the limit is
capped at ten times the enforceable loss. Exposure is gated by the bond and consumed by the draw.
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 (no key needed; given one it also reports the balance) ends by making a live
request to every Creditcoin-owned surface this depends on, so the list below is
checkable rather than asserted. A run on 2026-09-10:
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.
The pins are deliberate. Gluwa published @gluwa/asc-contracts 0.2.1 on 2026-08-31 under the new
ASC name, and the reference examples import from it; this tree stays on @gluwa/usc-contracts
0.1.2 and @gluwa/usc-sdk 0.18.0 (there is no newer SDK and no asc-sdk). 0.1.2's
EvmV1Decoder functions are public, which is why the decoder links as a deployed library at
0x5cab…df3F; 0.2.1 made them internal and dropped the type-specific decoders Utuh never calls.
The four it does call keep identical signatures in 0.2.1, and changing the pin changes bytecode
and breaks the Blockscout and Sourcify match of the live deployment, so the rename lands on the
merkle-claims branch, which redeploys anyway.
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
— 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.
markLoanAsExpiredisonlyOwner. 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.
Other bonded-claim designs have appeared on the same board. One bonds a predicate over a block
window and gives the bond to whoever proves one transaction that breaks it, which is the same shape
as a refutation here and covers the empty case: nothing bad happened. Its predicate sees one
proven transaction at a time and, in its own documentation, cannot sum history or compare two
transactions. So it can bond that a set is empty but not that a non-empty set is all of them. That
second sentence is the one a volume history or a repayment record needs, and it is what
UtuhCredit lends against. Absence here is the empty-set case of completeness, not the other way
round. The other difference is who looks: a bond deters only if someone searches, and Utuh ships
the search, as the browser sweep and npx -y utuh-mcp.
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 by 2026-08-28, when the fit
below was taken, 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 the 56 appends the published registries had seen by 2026-08-28, 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 term is not well determined, and it is worth saying so rather than quoting it.
An earlier fit over 25 appends put it at 20,526 gas — almost exactly a cold SSTORE, which was a
satisfying number and the reason to distrust it. Eleven more appends moved it to 61,265, and twenty
more to 81,427 while the calldata multiplier fell from 2.3× to 1.5× — the two terms trading against
each other, which is what collinear regressors do. Members
and bytes are correlated in this data (more members generally means more bytes), so separating the
two needs appends this repo has not made: many members with small transactions, and few with large
ones. What the data does support is the shape — fixed cost, a dominant per-byte cost, and some
per-member cost on top — not a precise value for the last of those.
The obvious missing term is the continuity proof, and it is instructive that it stays out. The
protocol prices verification almost entirely by it: the published figure is 2.3e-5 + 2.9e-7 × hashes CTC, so at the median proof here the hashes are more than half of what the precompile
charges. A fourth regressor for them fits better — worst residual 32% of a mean append down to
16% — and reports minus 860 gas a hash. A hashing operation cannot pay you. Every hash is 32
bytes of the same calldata the second term already charges for, so given nothing of its own to
explain it trades against that term instead, dragging it to 2.21×; reparameterised until both
coefficients are positive it prices a root byte at 0.53×, under the floor a byte can cost. So the
hashes are measured rather than fitted: hold every byte at its own EVM price, fit only what is
left, and the hashing comes out at 62 gas each — three specifications agree to within a gas,
and a keccak of two words is 42, so the number is the operation rather than an artifact. The
median append carries 94 of them and spends 5,866 gas on them, 0.6% of itself. The term that
dominates what the precompile charges is not the term that prices the claim.
The practical ceiling is therefore set by bytes:
a 100-event claim: 10 batches, ~24.5M gas, 0.3 full blocks of it
a 1,000-event claim: 100 batches, ~245.2M gas, 3.3 full blocks
a 10,000-event claim: 1000 batches, ~2451.6M gas, 32.7 full blocks
The asymmetry is still the point — challenging is one proof and a binary search, whatever the claim holds — but a claim of ten thousand events is about thirty-three full blocks of gas, and that is the number that caps this rather than any argument about storage.
Re-run on 2026-09-13 with the default GAS_LOOKBACK of 100,000 CC3 blocks — the mainnet
registry's last 85 transactions, 23 of them appends — the fit reads 317,593 fixed, 1.40× the
call's own calldata gas, 88,066 per member, worst residual 14% of the mean append, and 185 gas
per continuity hash with the bytes held at their own price; the ceiling comes out at 24.9M,
248.6M and 2,485.5M gas for 100, 1,000 and 10,000 events. The shape and the calldata term hold.
The per-member and per-hash terms move with the sample, which is what the paragraph above says
they do, and npm run gas prints whichever sample it was given rather than this one.
The subtle part
A challenge window is only meaningful if a watcher could actually have acted inside it. So a claim
may not open until its entire block range is already attested on Creditcoin — checked against the
ChainInfo precompile at 0x0FD3:
if (!CHAIN_INFO.is_height_attested(scope.chainKey, toBlock)) revert RangeNotAttested(...);
Without that gate, a claimant could cover a range whose tail is not yet attested, and the window
would expire on a claim nobody was able to refute. Attestation heights only advance, so once
toBlock is attested the whole range stays provable for the life of the claim.
A second detail: a refuter receives half the slashed bond, not all of it. If they took the whole bond, a claimant caught lying could refute their own claim and walk away whole, which would make a false claim free to attempt. The burned remainder is what puts a price on being wrong.
That price is smaller than the bond, and the difference matters. A claimant knows which event they omitted from the moment they seal, so they can watch for an incoming refutation and send their own from a second address, taking the refuter's share back. No ordering scheme closes this — an earlier draft of these notes claimed commit-reveal would, which was wrong: the claimant holds the private knowledge, so they simply commit first. What survives is the burn, which nobody can recover.
So the registry reports enforceableLoss rather than the bond, and isUsable measures exposure
against that. Sizing a line against the whole bond, as UtuhCredit did at first, carried twice
the exposure the deterrent actually covered.
Utuh MCP questions
How do I add Utuh MCP to Claude Code?
Run claude mcp add --env 'PRIVATE_KEY=<YOUR_PRIVATE_KEY>' utuh -- npx -y utuh-mcp in your terminal. Add --scope user to make it available in every project.
How do I add Utuh MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Utuh MCP provide?
It exposes 5 tools, including tally, list_claims, sweep_claim, refute_claim, audit_attestors.
How can an AI agent use this server?
An agent can hold the watcher role by running the server via npx or by connecting to the provided API endpoint.
What does Utuh actually do?
It bonds claims that a set of events is complete and pays out half the bond to anyone who can prove an event was omitted.
Can I verify the numbers in the repository myself?
Yes, you can run npm run judge to re-measure every number in the repository and the submission quote against the live chain.



