DEV Community: Fabian Bormann

I Have a Toy for You and You Will Like It: How to Play with the UVerify Sandbox

Fabian Bormann — Thu, 14 May 2026 19:20:34 +0000

If you read the previous article on the sandbox internals, you already know that there is a local playground, what it is made of, and roughly what it can do. What that article did not cover is how to actually play. This one does.

We will build a custom certificate template for a fictional institution called Building Block Academy, simulate issuing certificates in bulk for fictional students on the local devnet, evaluate the on-chain costs, and inspect the final issued certificates in the UI. At the end, we will submit the finished template to the public UVerify UI repository so anyone can see Building Block Academy's student certificates at app.uverify.io.

You will need:

Docker Desktop 24+
uv: brew install uv on macOS or the PowerShell one-liner on Windows
Deno: for the load test at the end
Claude Code: optional, but having an LLM handle the template styling saves a lot of time

Step 1: Scaffold a Template for Building Block Academy

The sandbox UI compiles templates at startup from a volume-mounted folder. You do not need the full uverify-ui source. The template add command scaffolds everything for you:

uv run sandbox.py template add BuildingBlockCertificate

Node.js is required here because the UVerify CLI runs via npx. The command creates sandbox/custom-ui-templates/BuildingBlockCertificate/ with a working React component and registers it in additional-templates.json.

Open the generated file:

open sandbox/custom-ui-templates/BuildingBlockCertificate/src/Certificate.tsx

The scaffold gives you a minimal but complete template that already renders its certificate hash, metadata, and the standard UVerify timestamp. It works out of the box. The next step is making it look like it belongs to Building Block Academy.

Step 2: Let Claude Design It

This is where the UVerify Claude skill comes in. Install it once:

/plugin marketplace add UVerify-io/uverify-claude-skill
/plugin install uverify@uverify-plugins

Then, in any Claude Code session opened at the uverify-examples folder, type:

/uverify

Claude now knows the full @uverify/core template API: the Template base class, layoutMetadata, render(), the UVerifyMetadata and UVerifyCertificateExtraData types, theming, and the uv_url_ prefix for keeping personal data off-chain.

Describe what you want. Something like:

I want a certificate template for Building Block Academy, an online blockchain education platform. Their landing page uses a dark navy background, gold accents, and a monospace font for hashes. The certificate should show the graduate's name, the course title, the completion date, and a short skills summary. The graduate's name should not be stored on-chain.

Claude will read Certificate.tsx, understand the layoutMetadata keys you need, and rewrite the component. The graduate's name goes into a uv_url_recipientName field so it stays off-chain but is still visible when someone visits the certificate URL. Everything else (course title, completion date, skills) gets stored as metadata.

From there, iterate freely. Ask Claude to adjust the font, swap the color scheme, add the academy logo as an SVG inline, or tighten the layout for mobile. The skill knows which props come from metadata, which come from extra, and which come from certificate, so you will not waste time debugging undefined values.

Step 3: Use the Local UVerify UI to Issue a Test Certificate

Once you are happy, start the sandbox:

uv run sandbox.py start --clean

Open http://localhost:3000, click Create, and enter a fictional student and certificate ID, for example Building-Block-Academy-00112233-998877665. Select your template from the Certificate Template dropdown, fill in the form fields, and click Use Demo Wallet. The Demo Wallet is a disposable wallet that gets funded automatically at that point. The certificate confirms on-chain in a second or two once you click Create Trust Certificate.

Step 4: Create a Data Plan

This was a single certificate. The real fun starts when you issue hundreds or thousands of certificates to see how the system performs at scale and what the on-chain costs look like. The simulator generates realistic bulk metadata from a plan file. Copy the example and shape it for Building Block Academy:

cp sandbox/simulator/plan.example.json sandbox/simulator/plan.buildingblock.json

Edit plan.buildingblock.json. A plan that fits the template you just built might look like this:

{
  "courseName":   { "type": "one-of", "values": [
    "Cardano Fundamentals", "Smart Contract Development with Aiken",
    "DeFi Protocol Design", "Blockchain Security", "NFT Engineering",
    "Governance and DRep Participation"
  ]},
  "completedAt":  { "type": "random-string", "regex": "202[45]-[01][0-9]-[0-2][0-9]" },
  "grade":        { "type": "one-of",        "values": ["Distinction", "Merit", "Pass"] },
  "creditsEarned":{ "type": "random-number", "range": { "min": 10, "max": 40 } },
  "issuer":       { "type": "static",        "value": "Building Block Academy" }
}

Plan files follow plan*.json naming and are gitignored (except plan.example.json), so your local plans stay local.

Step 5: Run the Simulator

uv run sandbox.py simulate \
  --template BuildingBlockCertificate \
  --plan sandbox/simulator/plan.buildingblock.json \
  --amount 1500 \
  --batch-size 15

The simulator generates 1,500 metadata files, then submits them in batches of 15 certificates per transaction. A wallet is created automatically on first run and funded from the sandbox faucet with three UTxOs of 500 ADA each, which is more than enough. The output looks like this:

[100/100] Submitting 15 certificate(s) …
  fe418affb5b3667aff7b95084eb8f80d9cc107e8d3492cbbaf6b1b6a7b4e87a2
  fe55c96ac1c9aa5adefc0d1d537a33bc0fcee078f1b26743b48f944481293611
  fe645b6d1028311cdeea7fd6843dea1954c77e8f402b478d7f8c5951fcf52602
  fedc52f9d7ff76d120f95d15350dcf7c335544594f049bf3061939f4a7768865
  fef65cd8837ec08ac03323592f139577565329c6f8f3498849accb045e42457c
  ff611fa073f82d8f431a2f5a75d9b9bdd2393da02ed77482f30a5c555e7e2906
  ff68fd08e764def25c9260549cd6980243e9f722718813aae9685fc63f8042e8
  ff7eb54740fbb0603fd93ae34c13aaa5addcd1ddb25dcaa4b5ad88b868d01f78
  ff8f452b8669ce0dd54488254bd5fc58e4649099d8f957a1f64da8d8b524896b
  ffa736097fbb0b172a51f6d8ee4a387233363a21d9858419badc7d31a019b797
  ffc76932e5986de882a0930114f70c05b2c538581529cb6a0f78ec23c184d8a2
  ffddf56aa793c118b559524ea7166e42dbb4fb144ce8c403338ec5c6cd49f192
  ffecfc988dfd16b38057b14d87bfb7f4a490459c63ca330c62c7a6eb0f5ce4e0
  fff9e33a293613dcf009711c9d355bd1bd31d71bef0117fa31ac125f7ca99d91
  fffdcca1145af6e495fd543a6999c8f5cb6d5e2c16cae5fa4e8d998acf1c67be
  tx:  5a79d808ea1ed3d63ad919b7a0f88ca22bd674a76c1f99fd8f440e02187f008d
  fee: 0.938905 ADA
  Waiting for confirmation …
  Confirmed ✓

──────────────────────────────────────────────────
Transactions : 100
Certificates : 1500
Total fees   : 105.029809 ADA
Results      : results.json

If your machine goes to sleep mid-run, the simulator saves progress to results.json after every confirmed transaction. On the next run it asks whether to continue or start over. Pick y and it skips the already-submitted hashes without resubmitting anything.

Batch size affects cost. Larger batches pack more certificates per transaction and drive the per-certificate fee down. The practical ceiling is around 70-80 certificates per transaction depending on metadata size, after which Plutus ExUnits become the limiting factor rather than the transaction size limit. If you just need a fingerprint and an Arweave hash or IPFS CID, you can fit more certificates per transaction and reduce costs further. Play around with it and see how it affects the total fees.

Step 6: Look at What You Made

Grab any certificate hash from the output (or from sandbox/simulator/results.json) and open it:

http://localhost:3000/verify/fe418affb5b3667aff7b95084eb8f80d9cc107e8d3492cbbaf6b1b6a7b4e87a2

Your Building Block Academy template renders with the metadata from that specific certificate: course name, grade, credits, date. The timestamp is the slot from the confirmed block. The issuer is the wallet address that signed the transaction. All of it is pulled directly from on-chain data. No database, no backend state.

You can also browse the raw transactions in Yaci Viewer at http://localhost:3001 and inspect the UTxOs in Yaci Store at http://localhost:8080.

Step 7: Share It with the World

The sandbox is great for development, but the real UVerify deployment at app.uverify.io can host your template too. To get it included:

Push your template to a public GitHub repository.
Pin an exact commit hash (no branch names or tags).
Open an issue on the uverify-ui repository using the Add External Template issue template.

The template asks for the repo URL, the pinned commit hash, the path to Certificate.tsx, a description of the use case, and a checklist confirming local testing. Submissions that pass the checklist review get added to additional-templates.json and become available at app.uverify.io for anyone to use. You can restrict who sees the template by adding a whitelist to the Certificate.tsx template class:

  public whitelist = [
    'addr1qyleluql6elu7sktvncqfufnq675hlt9z922ah9sm45dmp7kjn0vsay0vq28379mczjmglmam3svuxyka0tyw0uchwjqmxmhg3',
    'addr_test1qqleluql6elu7sktvncqfufnq675hlt9z922ah9sm45dmp7kjn0vsay0vq28379mczjmglmam3svuxyka0tyw0uchwjqcsxhyw',
  ];

Only certificates issued by one of those addresses will be visible in the UI.

Wrapping Up

You now have a running local Cardano devnet, a custom certificate template designed with AI assistance, and 1,500 demo certificates on-chain. Total time: an afternoon at most, probably less.

The sandbox resets cleanly with uv run sandbox.py start --clean whenever you want a fresh state. Your template files persist in sandbox/custom-ui-templates/ and survive the reset.

If something breaks or you want to show off what you built, the Discord is the right place. Full SDK and API documentation is at docs.uverify.io.

Now go build something real with it.

What a Playground: Building a Blockchain Sandbox with Yano and Yaci Store

Fabian Bormann — Mon, 04 May 2026 21:02:05 +0000

The Problem with Local Blockchain Development

Developing against a live blockchain network is slow by default. Transactions confirm in seconds at best. Reproducing a precise on-chain state for testing requires replaying a sequence of transactions in the right order, signed by the right keys.

The alternatives are mocking the chain or stubbing the indexer. Both trade one problem for another. You end up testing against a model of the blockchain rather than the blockchain itself. That gap has a way of hiding bugs until the worst possible moment.

For UVerify, we needed something better. The UVerify sandbox built with Yano and Yaci Store is the result.

The Stack

The UVerify sandbox runs six Docker services. Three of them are the interesting ones.

Yano is a local running Java Cardano node. It produces blocks, exposes a Cardano node-to-node (N2N) port for downstream indexers, and provides a Blockfrost-compatible REST API. It also ships with a snapshot API that lets you take a named checkpoint of the full RocksDB chain state and restore it later. That snapshot mechanism is the foundation everything else is built on.

Yaci Store is a full Cardano chain indexer, also from bloxbean. It connects to Yano's N2N port, syncs the chain from genesis, and exposes a rich REST API covering UTxOs, transactions, assets, epochs, staking pools, and governance data. The sandbox runs Yaci Store as a standalone Docker container on port 8080 with its own PostgreSQL schema.

Yaci Viewer is a block explorer built on top of Yaci Store. It runs at port 3001 and gives you a visual browser for every block, transaction, and UTxO the local devnet has produced. When you submit a test transaction and want to inspect its inputs and outputs, Yaci Viewer is where you look.

Yaci Store exposes a rich REST API documented via Swagger UI at http://localhost:8080/swagger-ui/index.html. The API surface covers UTxOs, transactions, assets, epochs, staking pools, governance, and more.

UVerify UI             http://localhost:3000
UVerify Backend        http://localhost:9090
UVerify API (Swagger)  http://localhost:9090/swagger-ui/index.html
Yaci Viewer            http://localhost:3001
Yaci Store API         http://localhost:8080
Yaci Store (Swagger)   http://localhost:8080/swagger-ui/index.html
Yano devnet API        http://localhost:7070/q/swagger-ui

The Snapshot: No Private Keys, No Transaction Replay

The most important property of the sandbox is what you do not have to do when you start it.

You do not need the private keys that were used to deploy the smart contracts. You do not need to replay the bootstrap sequence that funded the service wallet, initialized the proxy contract, or registered the bootstrap datum on-chain. All of that state is already present in the snapshot. Starting the sandbox restores it instantly.

The snapshot is a RocksDB checkpoint taken with Yano's snapshot API after a bootstrap.sh script ran through the full initialization sequence on a fresh chain. The resulting directory is bundled into the Yano Docker image:

docker cp "bloxbean-yano:/app/snapshots/uverify-base-state" ./yano/snapshots/
docker build -t uverify/sandbox-node:latest ./yano/

When sandbox.sh start runs and finds no existing chainstate volume, it seeds the Docker volume from that bundled snapshot before starting any services:

docker run --rm \
  -v "${CHAINSTATE_VOLUME}:/chainstate" \
  uverify/sandbox-node:latest \
  sh -c "cp -a /app/snapshots/uverify-base-state/checkpoint/. /chainstate/"

From that point forward, Yano starts from a chain that already has every contract deployed and every funding transaction confirmed. The UVerify backend connects, Yaci Store syncs from slot 0, and the whole environment is ready without you having to own, manage, or even know about the service wallet mnemonic.

Wall-Clock Catch-Up

There is one subtlety with restoring a snapshot: the chain stopped at a specific slot in the past. Cardano's KES (Key Evolving Signature) protocol has time-based validity windows. If the devnet node tries to produce blocks as if no time had passed, it will eventually fail key evolution checks.

Yano solves this with a single API call:

curl -X POST http://localhost:7070/api/v1/devnet/epochs/catch-up

This advances the local chain forward through all the intermediate epochs to reach the current wall-clock time. It runs in seconds regardless of how long ago the snapshot was taken. The sandbox.sh script calls it automatically after the node comes up, so by the time the rest of the services are healthy, the devnet is producing blocks at the correct epoch and slot.

This is the piece that makes the sandbox work correctly whether you started it an hour after the last snapshot was built or six months later.

Yaci Store as an Embedded Library

The standalone Yaci Store container handles the block explorer use case. But the UVerify backend has a different requirement: it needs to react to specific UTxOs arriving on-chain in real time, not poll a REST API.

The bloxbean ecosystem provides a yaci-store-spring-boot-starter library that embeds the Yaci Store indexing pipeline directly into a Spring Boot application. The UVerify backend uses this to run its own internal indexer alongside the application code.

The backend pulls in four Yaci Store starters:

<artifactId>yaci-store-spring-boot-starter</artifactId>
<artifactId>yaci-store-utxo-spring-boot-starter</artifactId>
<artifactId>yaci-store-transaction-spring-boot-starter</artifactId>
<artifactId>yaci-store-script-spring-boot-starter</artifactId>

To hook into the indexing pipeline, the backend provides a custom UVerifyStorage that extends UtxoStorageImpl:

@Component
@Profile("!disable-indexer")
public class UVerifyStorage extends UtxoStorageImpl {

    @Override
    public void saveUnspent(List<AddressUtxo> addressUtxoList) {
        List<AddressUtxo> processedByUVerifyCore =
            cardanoBlockchainService.processAddressUtxos(addressUtxoList);
        List<AddressUtxo> processedByExtensions =
            extensionManager.processAddressUtxos(addressUtxoList);
        List<AddressUtxo> processedByUVerifyProxy =
            hasBeenProcessedByUVerifyProxy(addressUtxoList);

        Set<AddressUtxo> allProcessed = new HashSet<>();
        allProcessed.addAll(processedByUVerifyCore);
        allProcessed.addAll(processedByExtensions);
        allProcessed.addAll(processedByUVerifyProxy);

        if (!allProcessed.isEmpty()) {
            super.saveUnspent(new ArrayList<>(allProcessed));
        }
    }

    @Override
    public int deleteUnspentBySlotGreaterThan(Long slot) {
        cardanoBlockchainService.handleRollbackToSlot(slot);
        extensionManager.handleRollbackToSlot(slot);
        return 0;
    }
}

Every time a new block arrives, Yaci Store calls saveUnspent with the list of new UTxOs. UVerifyStorage routes each UTxO through the core processing pipeline, the extension manager, and the proxy contract filter. Only UTxOs relevant to UVerify contracts are persisted. Rollbacks are handled the same way.

In the sandbox, the backend is pointed at Yano's N2N port via application-devnet.yml. The same code runs unchanged against preprod and mainnet by simply changing the target node host, port, and protocol magic. No conditional logic, no environment-specific branches.

Building and Destroying

Starting the sandbox is a single command:

./sandbox.sh start

If the chainstate volume already exists from a previous run, it resumes from where it left off. If you want to wipe everything and start from a clean snapshot:

./sandbox.sh start --clean

This stops all services, deletes the chainstate volume and the PostgreSQL data, and re-seeds from the bundled snapshot. The whole reset takes about a minute. When it finishes, every service is running and all URLs are printed to the terminal:

  Service                     URL
  ─────────────────────────   ──────────────────────────────────────────
  UVerify UI                  http://localhost:3000
  UVerify Backend             http://localhost:9090
  API docs (Swagger)          http://localhost:9090/swagger-ui/index.html
  Chain viewer                http://localhost:3001
  Yaci Store API              http://localhost:8080
  Yaci Store (Swagger)        http://localhost:8080/swagger-ui/index.html
  Yano devnet API             http://localhost:7070/q/swagger-ui

You get back a pristine environment with all contracts deployed, all wallets funded, and the chain caught up to wall time. The snapshot is deterministic, so the starting state is always identical no matter how many times you reset.

Faucet Mechanics

The sandbox includes a faucet wallet funded during the bootstrap sequence. When running examples, you request funds through the UVerify backend:

const client = new UVerifyClient({ baseUrl: 'http://localhost:9090', signMessage, signTx });
await client.waitFor(await client.fundWallet(address));

The backend faucet uses a FAUCET_MNEMONIC wallet to build and submit a real Cardano transaction. The transaction is confirmed on-chain, indexed by the embedded Yaci Store, and the UTxO is visible in Yaci Viewer.

Yano also exposes a direct fund endpoint at POST /api/v1/devnet/fund that injects UTxOs into the ledger state directly, without creating a transaction. This is useful during the bootstrap process when you need to seed wallets before any application logic is running. For normal example usage, the backend faucet is the right choice: it produces real confirmed transactions with real tx hashes.

Running the Examples

The uverify-examples repository contains nine examples across TypeScript, Python, and Java. Every example is self-contained: no shared utilities, no build system setup. Each one targets the sandbox by default.

TypeScript examples run with Deno:

cd uverify-examples/typescript/diploma
deno run -A index.ts

Python examples use uv with inline PEP 723 dependency declarations:

cd uverify-examples/python/diploma
uv run main.py

Java examples use JBang with //DEPS headers:

cd uverify-examples/java/diploma
jbang Diploma.java

Each example creates a wallet, requests funds from the faucet, issues a certificate, and prints the transaction hash and a verification URL. The wallet mnemonic is persisted to a local file so subsequent runs reuse the same address. You can watch each transaction arrive in Yaci Viewer at http://localhost:3001 while the example is running.

Getting Started

The sandbox requires Docker. Everything else is handled automatically.

git clone https://github.com/UVerify-io/uverify-examples.git
cd uverify-examples
./sandbox.sh start

That is the complete setup. All six services start from the snapshot, the chain advances to wall time, and the URLs are printed to the terminal.

If you run into an issue or want to discuss the tooling, join the Discord community or open an issue on GitHub.

The full SDK and API documentation is at docs.uverify.io.