DEV Community: Elliot lucky

Shielded Token Contracts on Midnight: Real Errors, Real Fixes

Elliot lucky — Wed, 01 Jul 2026 03:07:56 +0000

Written from months of grinding on shielded liquidity DeFi protocols on Midnight.

If you've been trying to build anything serious with shielded fungible tokens on Midnight lending protocols, liquidity pools, DEXes you've probably hit some walls that the documentation doesn't fully prepare you for. The Midnight programming model around shielded tokens is genuinely different from anything in the EVM world, and a lot of the intuitions you carry from Solidity or even other ZK environments will get you into trouble fast.

This post is a breakdown of the most impactful errors and misconceptions I ran into while building shielded liquidity DeFi contracts using Midnight's Compact language. These are not theoretical every single one of these either broke a circuit or caused a proof server failure at some point. I'll walk through what the issue is, why it happens, and what the correct pattern looks like.

Background: How Shielded Tokens Actually Work Under the Hood

Before we get into the errors, let's get clear on the underlying mechanics because this context is what makes the errors make sense.

Midnight uses a protocol called Zswap for shielded token operations. When a user sends tokens to your contract by calling receiveShielded, what actually happens is more involved than it looks on the surface.

When your circuit calls receiveShielded(coin), the Compact runtime records a shielded receive obligation in the transaction being constructed. At this point, the proof server kicks in to generate the ZK proof for your circuit. But here's the thing your circuit only describes what the contract side is doing. The transaction still needs to be balanced: the tokens being received by the contract have to come from somewhere.

This is where the wallet gets involved through an internal mechanism that runs beneath your circuit. The wallet looks at the ShieldedCoinInfo you're receiving the coin's color (token type) and value and finds a matching UTXO in the user's private coin set. It then generates a Zswap ownership proof a ZK proof that proves the wallet owns a valid commitment in the global shielded ledger (via a nullifier), without revealing which UTXO it is. This proof is what actually authorizes the spending of the user's tokens.

The ShieldedCoinInfo that you receive in your circuit as a parameter is essentially the user's declaration: "I have a coin of this color and this value that I'm sending you." The wallet is the one that provides the actual cryptographic evidence backing that claim. The proof server then bundles your circuit's proof together with the wallet's Zswap proof into a single transaction that satisfies all the balance constraints.

This is why ShieldedCoinInfo has to arrive as a circuit parameter it has to exist before the proof is constructed so the wallet knows what to balance against. You cannot dynamically request coins inside a circuit in a way the wallet didn't know about from the start.

// The coin comes in as a circuit parameter - the wallet uses this
// to find the matching UTXO and generate its Zswap ownership proof
export circuit deposit(incomingCoin_: ShieldedCoinInfo): [] {
    const incomingCoin = disclose(incomingCoin_);
    // At this point, the wallet has already committed to providing
    // a UTXO matching incomingCoin.color and incomingCoin.value
    receiveShielded(incomingCoin);
    // ...
}

With that foundation in place, let's get into the errors.

Error 1: Multiple Separate Shielded Balance Mappings

The mistake: Creating separate ledger fields for each type of shielded asset the contract holds, or trying to manage shielded balances across multiple independent QualifiedShieldedCoinInfo ledger fields.

// DON'T do this
export ledger assetABalance: QualifiedShieldedCoinInfo;
export ledger assetBBalance: QualifiedShieldedCoinInfo;
export ledger assetCBalance: QualifiedShieldedCoinInfo;
// ...and growing as you add more assets

Why it fails: The moment you try to receive or send shielded tokens from multiple separate ledger fields in anything but the most trivial scenarios, you'll start hitting proof construction issues and ledger state inconsistencies. It also completely kills your extensibility you can't add a new supported asset without changing the contract's ledger schema.

The correct pattern: One Map<Bytes<32>, QualifiedShieldedCoinInfo> keyed by coin color. That's your single source of truth for everything the contract holds in shielded form. Separate tracking for accounting, positions, pool states all of that can live in whatever structure you want (Maps, commitments, Merkle trees). But the actual shielded custody is one map.

// ONE mapping to manage all shielded holdings
export ledger contractShieldedBalance: Map<Bytes<32>, QualifiedShieldedCoinInfo>;

// Separate ledgers for your protocol accounting - no shielded tokens here
export ledger userPositions: Map<Bytes<32>, UserPosition>;
export ledger assetConfigs: Map<Bytes<32>, AssetConfig>;

The QualifiedShieldedCoinInfo returned by operations like insertCoin or mergeCoinImmediate already encapsulates the UTXO pointer the contract needs to spend from. You want all of that living in one place, keyed by color, so any circuit that needs to receive or send a particular asset knows exactly where to look.

Error 2: Receiving and Sending from the Same Contract Balance in One Circuit

This one caused the most confusing errors. The symptom is a public mismatch error from the proof server which is cryptic enough that you might chase it for a while before finding the root cause.

The mistake: Writing a single circuit that both receives shielded tokens into the contract balance (receiveShielded then update your balance map) and sends shielded tokens from the same balance map (sendShielded) for the same coin type.

The intuition that leads you here is natural in a two-sided operation like a collateral deposit paired with a loan payout, you want to take in one token and release another in the same transaction. In a liquidity rebalance, you take in one asset and send another. Seems like one atomic operation. It isn't, at least not when both sides touch the same QualifiedShieldedCoinInfo.

Why it fails: When your circuit calls receiveShielded, it marks that UTXO slot as modified in one direction. When it calls sendShielded from the same balance map entry, the proof server tries to reconcile the public inputs/outputs for that UTXO across both operations in the same proof and the balance equations don't hold cleanly. This manifests as the public input mismatch error.

The correct pattern: Split the operation into two circuits one for receiving, one for sending.

// Phase 1: receive the incoming token, update contract balance, mark state as pending
export circuit actionReceive(incomingCoin_: ShieldedCoinInfo): [] {
    const incomingCoin = disclose(incomingCoin_);
    // ... validate, update accounting state ...

    receiveShielded(incomingCoin);

    const existing = contractShieldedBalance.member(incomingCoin.color)
        ? mergeCoinImmediate(contractShieldedBalance.lookup(incomingCoin.color), incomingCoin)
        : incomingCoin;

    contractShieldedBalance.insertCoin(
        incomingCoin.color,
        existing,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );

    // Flag that the send side is pending
    userState.insert(userKey, { ...currentState, status: Status.sendPending });
}

// Phase 2: send from contract balance, clear pending state
export circuit actionSend(outgoingCoinColor_: Bytes<32>): [] {
    const outgoingCoinColor = disclose(outgoingCoinColor_);
    const state = userState.lookup(userKey);
    assert(state.status == Status.sendPending, "Send is not pending");

    // Only sending here - no receiveShielded in this circuit
    const balance = contractShieldedBalance.lookup(outgoingCoinColor);
    const result = sendShielded(balance, left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey()), state.pendingAmount);

    if (result.change.is_some) {
        contractShieldedBalance.insertCoin(outgoingCoinColor, result.change.value, right<ZswapCoinPublicKey, ContractAddress>(kernel.self()));
    } else {
        contractShieldedBalance.remove(outgoingCoinColor);
    }

    userState.insert(userKey, { ...state, status: Status.settled, pendingAmount: 0 });
}

The two-phase pattern also gives you a cleaner state machine for your protocol. The pending status flags aren't just organizational they're the safety check that ensures the second circuit can only run after the first one completed successfully on-chain.

There are two specific cases where you can mix shielded operations in one circuit, and they work fine because they don't touch the same QualifiedShieldedCoinInfo on both sides:

Case A: receiveShielded + mintShieldedToken You're receiving one type of token (into your balance map) and minting a different token (LP tokens, receipt tokens, etc.) directly to the user. No conflict because mint creates a new UTXO that wasn't in the contract's balance.

// Works fine: receive principal token, mint a receipt token to user
export circuit depositAndMintReceipt(incomingCoin_: ShieldedCoinInfo): [] {
    const incomingCoin = disclose(incomingCoin_);

    receiveShielded(incomingCoin);

    const existing = contractShieldedBalance.member(incomingCoin.color)
        ? mergeCoinImmediate(contractShieldedBalance.lookup(incomingCoin.color), incomingCoin)
        : incomingCoin;

    contractShieldedBalance.insertCoin(
        incomingCoin.color,
        existing,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );

    // Mint a receipt token of a completely different color to the user
    mintShieldedToken(
        receiptTokenDomainSeparator,
        incomingCoin.value,
        mintNonce(),
        left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey())
    );
}

Case B: receiveShielded + sendImmediateShielded You receive a token and immediately send it to the burn address (or anywhere else) without going through the contract's managed balance map. The sendImmediate family of operations routes tokens directly without touching the contract's stored QualifiedShieldedCoinInfo, so there's no conflict. This is the correct pattern for burning.

// Works fine: receive a receipt token from user, burn it immediately
export circuit burnReceiptAndWithdraw(receiptCoin_: ShieldedCoinInfo, underlyingCoinColor_: Bytes<32>): [] {
    const receiptCoin = disclose(receiptCoin_);
    const underlyingColor = disclose(underlyingCoinColor_);
    const burnAddr = shieldedBurnAddress();

    receiveShielded(receiptCoin);
    sendImmediateShielded(receiptCoin, burnAddr, receiptCoin.value); // burn receipt token directly

    // Now send the underlying asset FROM the contract balance (different coin type = no conflict)
    const balance = contractShieldedBalance.lookup(underlyingColor);
    const withdrawAmount = calculateWithdrawable(receiptCoin.value);
    const result = sendShielded(balance, left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey()), withdrawAmount);

    if (result.change.is_some) {
        contractShieldedBalance.insertCoin(underlyingColor, result.change.value, right<ZswapCoinPublicKey, ContractAddress>(kernel.self()));
    } else {
        contractShieldedBalance.remove(underlyingColor);
    }
}

Error 3: Treating Shielded Token Balance Like an Unshielded Balance

If you're coming from building unshielded token contracts on Midnight, you might expect the contract runtime to track your shielded holdings automatically. It doesn't.

With unshielded tokens, the runtime handles the accounting your contract just calls the right transfer functions and the ledger reflects what's there. Shielded tokens work completely differently. The contract has no automatic awareness of what shielded UTXOs it holds. If you receive a shielded deposit and don't explicitly track it in a ledger field, that UTXO is effectively lost you can't spend it because you have no reference to it.

The QualifiedShieldedCoinInfo type is what gives you that reference. It's the pointer from your contract's ledger into the shielded UTXO set. Without it, you cannot call sendShielded.

export ledger contractShieldedBalance: Map<Bytes<32>, QualifiedShieldedCoinInfo>;

export circuit receiveDeposit(incomingCoin_: ShieldedCoinInfo): [] {
    const incomingCoin = disclose(incomingCoin_);

    receiveShielded(incomingCoin);

    // Without this insertCoin call, the tokens are received but permanently unspendable
    const coinToStore = contractShieldedBalance.member(incomingCoin.color)
        ? mergeCoinImmediate(contractShieldedBalance.lookup(incomingCoin.color), incomingCoin)
        : incomingCoin;

    contractShieldedBalance.insertCoin(
        incomingCoin.color,
        coinToStore,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
}

The insertCoin call is what binds the received UTXO to your contract's ledger state. Skip it and you've essentially sent tokens into a black hole.

Best Practice 4: Always Receive ShieldedCoinInfo as a Circuit Parameter

This one is less a confirmed error and more a pattern I've settled on firmly: always accept ShieldedCoinInfo as a circuit parameter before calling receiveShielded. Do not attempt to derive or build the coin info from other inputs inside the circuit body.

The reason this matters comes down to how the proof system works. The wallet needs to see the ShieldedCoinInfo at the point of transaction construction so it can identify the matching UTXO from the user's private coin set and generate its Zswap ownership proof. The circuit parameters are what the wallet reads to know what to balance against. If the coin information isn't surfaced as a parameter, the wallet has no clean way to participate in the proof at the right time.

The correct pattern: Accept ShieldedCoinInfo as a parameter, disclose it inside the circuit, then pass it to receiveShielded.

// The coin arrives as a parameter - the wallet can read it and balance accordingly
export circuit deposit(incomingCoin_: ShieldedCoinInfo): [] {
    const incomingCoin = disclose(incomingCoin_);
    receiveShielded(incomingCoin);
    // ...
}

The frontend or CLI is responsible for constructing the ShieldedCoinInfo from the user's wallet (the wallet API exposes the user's available coins), then passing it as a parameter to the circuit call. The wallet then handles the UTXO selection and ownership proof on its side.

Error 5: Storing Each Deposit as an Independent UTXO

The mistake: Instead of merging new deposits into a single QualifiedShieldedCoinInfo balance, someone might reach for a Set<QualifiedShieldedCoinInfo> to accumulate UTXOs, thinking they can collect them all and deal with selection later.

// DON'T do this - accumulating independent UTXOs in a set
export ledger assetUTXOs: Set<QualifiedShieldedCoinInfo>;

export circuit deposit(incomingCoin_: ShieldedCoinInfo): [] {
    const incomingCoin = disclose(incomingCoin_);

    receiveShielded(incomingCoin);

    // Each deposit added as its own independent UTXO entry
    assetUTXOs.insertCoin(incomingCoin);
}

Why this is a problem: When the contract needs to send, sendShielded takes a single QualifiedShieldedCoinInfo as input. If your liquidity is spread across a set of independent UTXOs, you now have to filter and sort through them to find entries that cover the amount you need, handle partial coverage across multiple entries, and manually merge before you can send anything. That logic is complex, brittle, and entirely avoidable. You end up writing significant off-chain UTXO selection code for a problem that doesn't need to exist.

The correct pattern: Always merge deposits into a single aggregated balance per coin color using mergeCoinImmediate. One coin color = one QualifiedShieldedCoinInfo entry in your map. When you deposit, merge. When you send, the single entry has everything you need.

export circuit deposit(incomingCoin_: ShieldedCoinInfo): [] {
    const incomingCoin = disclose(incomingCoin_);

    receiveShielded(incomingCoin);

    // Merge into existing balance, or initialize if first deposit of this type
    const aggregated = contractShieldedBalance.member(incomingCoin.color)
        ? mergeCoinImmediate(contractShieldedBalance.lookup(incomingCoin.color), incomingCoin)
        : incomingCoin;

    contractShieldedBalance.insertCoin(
        incomingCoin.color,
        aggregated,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
}

mergeCoinImmediate is provided by the Compact standard library exactly for this purpose combining multiple UTXOs of the same coin type into a single QualifiedShieldedCoinInfo. Use it.

Error 6: Not Handling Change After Sending

This one is subtle. When your contract calls sendShielded to send tokens to a user, the operation doesn't automatically return the change to the contract. You have to handle it explicitly.

Think of it like spending cash if you hand over a 100-unit note to pay for something that costs 70, you need to receive 30 back. If you don't explicitly handle that change, it evaporates.

The mistake:

export circuit withdraw(coinColor_: Bytes<32>, amount: Uint<128>, receiver: ZswapCoinPublicKey): [] {
    const coinColor = disclose(coinColor_);
    const balance = contractShieldedBalance.lookup(coinColor);
    sendShielded(balance, left<ZswapCoinPublicKey, ContractAddress>(receiver), amount);
    // BUG: change is lost. contractShieldedBalance still points to a spent UTXO.
    // The next attempt to send from this color will fail.
}

The correct pattern: sendShielded returns a result that contains the change (if any). Check it. If there's change, put it back into your balance map. If the balance is fully spent, remove the entry.

export circuit withdraw(coinColor_: Bytes<32>, amount: Uint<128>, receiver: ZswapCoinPublicKey): [] {
    const coinColor = disclose(coinColor_);
    assert(contractShieldedBalance.member(coinColor), "No balance for this coin type");
    assert(amount > 0, "Invalid send amount");

    const balance = contractShieldedBalance.lookup(coinColor);
    const result = sendShielded(
        balance,
        left<ZswapCoinPublicKey, ContractAddress>(receiver),
        amount
    );

    // Always handle the change
    if (result.change.is_some) {
        contractShieldedBalance.insertCoin(
            coinColor,
            result.change.value,
            right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
        );
    } else {
        contractShieldedBalance.remove(coinColor); // fully spent, clean up
    }
}

If you skip this and your contract later tries to call sendShielded on a coin color whose UTXO was already spent in a previous transaction, the transaction will fail because the UTXO no longer exists in the ledger.

Putting It All Together: The Pattern That Works

Combining all of the above, here's the mental model for shielded token management that I now use in every contract:

State design:

One Map<Bytes<32>, QualifiedShieldedCoinInfo> as the single source of truth for all shielded holdings
All other accounting (user positions, asset configs, protocol state) in separate non-shielded ledger structures

Receive pattern:

Accept ShieldedCoinInfo as a circuit parameter
Call receiveShielded on the disclosed coin
Merge into the balance map with mergeCoinImmediate

Send pattern:

Lookup from the balance map
Call sendShielded, capture the result
Handle change or remove the entry

Split circuits wherever both sides touch the same QualifiedShieldedCoinInfo:

Receive in one circuit, update state to pending
Send in a separate circuit, verify pending state, execute, finalize

Safe exceptions where you can combine in one circuit:

Receiving a token + minting a different token (LP tokens, receipt tokens)
Receiving a token + sendImmediate to burn it (doesn't touch the balance map)

References

Compact Standard Library receiveShielded, sendShielded, sendImmediateShielded, mintShieldedToken, mergeCoinImmediate: docs.midnight.network/develop/reference/compact
Shielded token concepts and QualifiedShieldedCoinInfo: docs.midnight.network/develop/guides/shielded-tokens
Zswap protocol overview: docs.midnight.network/learn/zswap
Transaction balancing and proof construction: docs.midnight.network/develop/guides/transactions

These patterns took real trial and error to arrive at. The proof server errors in particular are notoriously unhelpful when you're deep in the wrong abstraction a "public mismatch" message doesn't tell you that you're trying to receive and send from the same balance in one circuit. Hopefully this saves someone else those hours.

If you're building shielded DeFi on Midnight and running into something I didn't cover here, feel free to reach out.

Follow Me on X: https://x.com/codebigint_01

Build a Private Vault DApp Smart Contract on Midnight with Compact

Elliot lucky — Mon, 27 Apr 2026 01:25:37 +0000

In this guide, we will build a vault dApp smart contract from scratch using Compact on Midnight.

The goal is to help developers who already know the basics of Compact start writing a complete smart contract that handles real vault behavior: receiving shielded tokens, tracking user vault balances, accumulating multiple deposits, and withdrawing funds.

We will focus on the contract side of the dApp. There is no frontend in this guide. The point is to understand the smart contract mechanics clearly before adding UI complexity.

What We Are Building

We are building a shielded token vault contract where a user can:

deposit a shielded coin into the vault
automatically create a vault on the first deposit
keep later deposits accumulated in the same vault
reject deposits with the wrong coin color
withdraw from the vault
keep the contract's shielded UTXO balance updated manually

The final project has this shape:

vault-dapp/
|-- package.json
|-- src/
|   |-- vault.compact
|   |-- witness.ts
|   |-- managed/
|   `-- test/
|       |-- vault.test.ts
|       |-- vault-setup.ts
|       `-- utils.ts
`-- tsconfig.json

The core files are:

src/vault.compact: the Compact smart contract
src/witness.ts: the TypeScript witness implementation
src/test/vault-setup.ts: the simulator setup
src/test/vault.test.ts: the behavior tests

Requirements

To follow along, you should already have:

your Midnight developer environment set up
the Compact toolchain installed
basic Compact knowledge
Bun installed
a code editor

Make sure your Compact compiler version matches the language version used in this project. This contract was built against Compact compiler 0.31.0 and language version 0.23.0, so the pragma is pinned:

pragma language_version 0.23.0;

Pinning the pragma avoids drift when newer compiler versions introduce language changes.

You will also want the Compact standard library and Ledger data type documentation open because we be will using the following:

Step 1: Create the Project

Create the folder:

mkdir vault-dapp
cd vault-dapp

Initialize the project with Bun:

bun init

Choose the blank template. Bun will create the initial package.json.

Then create the source folder and the Compact file:

mkdir src
touch src/vault.compact

Step 2: Add Compile Scripts

Before writing the full contract, add scripts so you do not have to keep typing the Compact compiler command manually.

In package.json, add:

{
  "scripts": {
    "test-compile": "compact compile --skip-zk src/vault.compact ./src/managed",
    "compile": "compact compile src/vault.compact ./src/managed"
  }
}

The test-compile script compiles the Compact code without generating the full zero-knowledge materials. That makes it useful while you are actively developing.

The compile script performs the full compile.

Both scripts write generated artifacts into:

src/managed

If that folder does not exist, the compiler creates it.

Step 3: Start the Compact Contract

Open src/vault.compact.

The first line is the pinned language pragma:

pragma language_version 0.23.0;

Then import the standard library:

import CompactStandardLibrary;

The standard library gives us access to the built-in circuits and types we need for token transfer, ledger helpers, hashing, and shielded coin management.

Step 4: Add the Main Circuit Skeleton

The vault has two exported circuits:

export circuit deposit(
    _coin: ShieldedCoinInfo
): []{
}

export circuit withdraw(_amount: Uint<128>): []{
}

These are the user-facing actions:

deposit: deposit shielded tokens into the contract, creating the user's vault on the first deposit
withdraw: withdraw shielded tokens from the contract

Run a quick compile to confirm the setup works:

bun run test-compile

If the setup is correct, Compact generates the managed TypeScript artifacts in src/managed.

Step 5: Define the Vault Struct

Now we define the shape of a vault position:

export struct Vault {
    balance: Uint<128>;
    coinColor: Bytes<32>;
    ownerHash: Bytes<32>;
}

The vault stores:

balance: the amount deposited into the vault
coinColor: the token color this vault accepts
ownerHash: a commitment to the public key that owns the vault

On Midnight, token types are identified by a byte string called a color. Different assets have different colors, so we use coinColor to make sure a user keeps one vault position tied to one asset type.

The final code uses Uint<128> for balance because ShieldedCoinInfo.value is also Uint<128>. If you use Uint<64> for balance, the compiler will complain when you add a coin value to the vault balance.

Privacy Trade-Off

This tutorial keeps the contract intentionally small, but the design has an important privacy trade-off.

The shielded coin itself is private, and token movement uses receiveShielded and sendShielded. However, each Vault.balance is stored as a plain Uint<128> in a public Map, and each vault also stores the accepted coinColor. That means the contract publicly exposes each vault's running accounting balance and asset color, even though the underlying coin is shielded.

This is acceptable for a learning example focused on shielded token handling and UTXO management. A production privacy-first vault should usually keep per-user balances in private state and store only commitments on-chain, for example with a Merkle-tree based design that proves balance updates without exposing each user's balance.

Step 6: Add Ledger State

We need one ledger map for vault positions:

export ledger vaults: Map<Bytes<32>, Vault>;

This maps a generated user ID to a vault.

We also need another map to manage shielded coin balances:

export ledger balances: Map<Bytes<32>, QualifiedShieldedCoinInfo>;

This map stores contract-held shielded coins by coin color.

This part is important: when you deal with shielded tokens, the contract does not automatically maintain an easy balance table for you. You receive the shielded coin, but you still need to manage the resulting UTXO state yourself. That is why the balances map exists.

ShieldedCoinInfo vs QualifiedShieldedCoinInfo

ShieldedCoinInfo represents a newly created shielded coin used when receiving or spending a coin in a transaction. It has fields such as:

nonce
color
value

QualifiedShieldedCoinInfo represents a shielded coin that already exists on the ledger and is ready to be spent. It includes the extra information needed to locate it, such as the Merkle tree index.

That is why:

deposits accept ShieldedCoinInfo
contract balances are stored as QualifiedShieldedCoinInfo
insertCoin converts the received shielded coin into the qualified form stored in the ledger

Step 7: Add the Witness Function

We do not want to store the user's raw secret in public ledger state.

Instead, we derive a user ID from a secret key stored in the user's private state.

Declare the witness:

witness getSecretKey(): Bytes<32>;

getSecretKey() lets the contract receive the user's secret key from private state during execution.

Step 8: Generate a User ID

Now add a helper circuit:

circuit generateUserId(sk: Bytes<32>): Bytes<32>{
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "vaul:user"),
        sk
    ]);
}

persistentHash gives us a deterministic ID from:

a fixed domain separator
the user's secret key

This is the commitment-based per-user identity used by the vault. It is the part of the design that lets the contract track balances by a commitment derived from private witness data instead of by storing a raw user address.

The current code uses "vault:user" as the domain separator. For a real deployed contract, choose this string carefully before deployment because changing it later changes all derived user IDs.

Step 9: Add the Owner Commitment Helper

The owner commitment stores a hash of the public key used when the vault is first created:

circuit generateOwnerCommitment(pk: Bytes<32>): Bytes<32>{
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "vault:owner:commitment"),
        pk
    ]);
}

This is not meant to reveal the public key as a raw field in the vault. The vault stores only the commitment hash.

Step 10: Implement deposit

The user deposits a shielded coin:

export circuit deposit(
    _coin: ShieldedCoinInfo
): []{
    const coin = disclose(_coin);

    receiveShielded(coin);

receiveShielded validates that the coin is being received by the contract in this transaction.

But receiving is not enough. The contract still needs to store or update the shielded balance manually.

If there is already a balance for this coin color, merge the previous ledger coin with the new coin:

if(balances.member(coin.color)){
    const prevBalance = balances.lookup(coin.color);
    const newBalance = mergeCoinImmediate(prevBalance, coin);

    balances.insertCoin(
        coin.color,
        newBalance,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
}else{
    balances.insertCoin(
       coin.color,
       coin,
       right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
}

Why mergeCoinImmediate?

mergeCoin is for merging two coins that already exist on the ledger. In this case, we are merging an existing QualifiedShieldedCoinInfo with a new incoming ShieldedCoinInfo, so we use mergeCoinImmediate.

Why right<ZswapCoinPublicKey, ContractAddress>(kernel.self())?

The recipient type can be either a user public key or a contract address. Since the contract is storing this balance for itself, we pass the contract address using the right constructor.

Next, derive the user ID:

const userId = generateUserId(disclose(getSecretKey()));
const hasVault = vaults.member(userId);

On the first deposit, create the vault:

if(!hasVault){
    const ownerCommitmentHash = generateOwnerCommitment(ownPublicKey().bytes);

    const newVault = Vault {
        balance: coin.value,
        coinColor: disclose(coin.color),
        ownerHash: ownerCommitmentHash
    };

    vaults.insert(userId, newVault);
}

On later deposits, require the same coin color and add the new amount to the existing balance:

else{
    const vault = vaults.lookup(userId);

    assert (coin.color == vault.coinColor, "Invalid coin type deposited");

    const updatedVault = Vault {
        ...vault,
        balance: (vault.balance + coin.value) as Uint<128>
    };

    vaults.insert(userId, updatedVault);
}

The cast to Uint<128> matters because coin.value is Uint<128>.

Run the compile script again:

bun run test-compile

Step 11: Implement withdraw

The withdrawal circuit accepts an amount:

export circuit withdraw(_amount: Uint<128>): []{
    const amount = disclose(_amount);
    const userId = generateUserId(disclose(getSecretKey()));

Reconstruct the owner commitment from the public key creating the transaction:

const reconstructedOwnerHash = generateOwnerCommitment(ownPublicKey().bytes);

Check that the user has a vault:

assert (vaults.member(userId), "You have no vault position");

Load the vault and check the user has enough balance:

const vault = vaults.lookup(userId);
assert (vault.balance >= amount, "Insufficient vault balance");

Then verify that the current public key matches the owner commitment stored when the vault was created:

assert (reconstructedOwnerHash == vault.ownerHash, "Unauthorized: You are not the owner");

Load the contract-held shielded coin for the vault's coin color:

const balanceToSendFrom = balances.lookup(vault.coinColor);

Now call sendShielded:

const sendResult = sendShielded(
    balanceToSendFrom,
    left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey()),
    amount
);

sendShielded sends a value from a shielded coin owned by the contract to a recipient.

Here the recipient is the user creating the transaction, so we use:

left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey())

When to use ownPublicKey()

ownPublicKey() is useful when a circuit needs the current transaction creator's public key as the target of an operation, for example sending a shielded coin to the caller.

Do not treat ownPublicKey() as a substitute for a verified private identity by itself. If a circuit authorizes access to private-account state, bind that access to private witness data or to a commitment established earlier in the contract. In this vault, the public key is committed into ownerHash when the vault is first created, and withdrawal checks that same commitment before sending funds.

After sending, Compact returns a send result. The important part for this contract is the change. If there is change left, we must store it. If there is no change, we remove the balance entry:

if(sendResult.change.is_some){
    balances.insertCoin(
        vault.coinColor,
        sendResult.change.value,
        right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
    );
}else{
    balances.remove(vault.coinColor);
}

Then reduce the user's vault balance:

const updatedVault = Vault {
    ...vault,
    balance: (vault.balance - amount) as Uint<128>
};

vaults.insert(userId, updatedVault);

Run the compile script again:

bun run test-compile

If you see an error around ownPublicKey, check the capitalization. It should be:

ownPublicKey()

Full Contract

Here is the complete src/vault.compact:

/**
 * Minimal Single Shielded Token Type Vault Dapp
 *
 * Key Concept demonstrated:
 *  Structured onchain pattern for contract state management involving Maps, Struct and hashes
 *  Shielded liquidity managment techniques using using receiveShielded and sendShielded
 *  Risk managment for private state compromise scenario using generateOwnerCommitment and ownerHash field for ownership verification
 *
 * NB: In this contract individual vault balance is publicly visible onchain which is a trade-off to keep the contract minimal as the focus
 * of this example is to demonstrate shielded token management. Usually individual shielded token balance should be kept in private state while commitments are stored onchain
 * utilzing ADT types like Merkle trees (completely shielded and verifiable by zk proof) or Maps 
 */
pragma language_version 0.23.0;
import CompactStandardLibrary;

export struct Vault {
    balance: Uint<128>;
    coinColor: Bytes<32>;
    ownerHash: Bytes<32>;
}

export ledger vaults: Map<Bytes<32>, Vault>;
export ledger balances: Map<Bytes<32>, QualifiedShieldedCoinInfo>;

witness getSecretKey(): Bytes<32>;

export circuit deposit(
    _coin: ShieldedCoinInfo
): []{
    const coin = disclose(_coin);

    receiveShielded(coin);

    if(balances.member(coin.color)){
        const prevBalance = balances.lookup(coin.color);
        const newBalance = mergeCoinImmediate(prevBalance, coin);

        balances.insertCoin(
            coin.color,
            newBalance,
            right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
        );
    }else{
        balances.insertCoin(
           coin.color,
           coin,
           right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
        );
    }

    const userId = generateUserId(disclose(getSecretKey()));
    const hasVault = vaults.member(userId);

    if(!hasVault){
        const ownerCommitmentHash = generateOwnerCommitment(ownPublicKey().bytes);

        const newVault = Vault {
            balance: coin.value,
            coinColor: disclose(coin.color),
            ownerHash: ownerCommitmentHash
        };

        vaults.insert(userId, newVault);
    }else{
        const vault = vaults.lookup(userId);

        assert (coin.color == vault.coinColor, "Invalid coin type deposited");

        const updatedVault = Vault {
            ...vault,
            balance: (vault.balance + coin.value) as Uint<128>
        };

        vaults.insert(userId, updatedVault);
    }
}

export circuit withdraw(_amount: Uint<128>): []{
    const amount = disclose(_amount);
    const userId = generateUserId(disclose(getSecretKey()));

    const reconstructedOwnerHash = generateOwnerCommitment(ownPublicKey().bytes);

    assert (vaults.member(userId), "You have no vault position");

    const vault = vaults.lookup(userId);
    assert (vault.balance >= amount, "Insufficient vault balance");

    assert (reconstructedOwnerHash == vault.ownerHash, "Unauthorized: You are not the owner");

    const balanceToSendFrom = balances.lookup(vault.coinColor);

    const sendResult = sendShielded(
        balanceToSendFrom,
        left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey()),
        amount
    );

    if(sendResult.change.is_some){
        balances.insertCoin(
            vault.coinColor,
            sendResult.change.value,
            right<ZswapCoinPublicKey, ContractAddress>(kernel.self())
        );
    }else{
        balances.remove(vault.coinColor);
    }

    const updatedVault = Vault {
        ...vault,
        balance: (vault.balance - amount) as Uint<128>
    };

    vaults.insert(userId, updatedVault);
}

circuit generateUserId(sk: Bytes<32>): Bytes<32>{
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "vaul:user"),
        sk
    ]);
}

circuit generateOwnerCommitment(pk: Bytes<32>): Bytes<32>{
    return persistentHash<Vector<2, Bytes<32>>>([
        pad(32, "vault:owner:commitment"),
        pk
    ]);
}

Step 12: Implement the TypeScript Witness

The Compact file declares the witness. TypeScript provides the runtime implementation.

Create src/witness.ts:

import {WitnessContext} from "@midnight-ntwrk/compact-runtime";
import type { Ledger } from "./managed/contract";

export interface VaultPrivateState {
    secretKey: Uint8Array
}

export function createVaultPrivateState(secretKey: Uint8Array): VaultPrivateState{
    return {
        secretKey
    }
}

export const witnesses = {
    getSecretKey: (
        {privateState}: WitnessContext<Ledger, VaultPrivateState>
    ): [VaultPrivateState, Uint8Array] => {
        return [privateState, privateState.secretKey]
    },
}

The witness returns a tuple:

[privateState, witnessValue]

In this project, the private state does not change, so the witness returns the same private state it received.

Step 13: Test the Contract

The final project includes Vitest tests around the generated contract bindings.

The simulator in src/test/vault-setup.ts deploys the generated Contract, initializes private state, and exposes helper methods:

deposit(amount: bigint, color = TEST_COIN_COLOR): Ledger
withdraw(amount: bigint): Ledger

The tests cover:

deploying with empty ledgers
creating a vault on the first valid deposit
accumulating two deposits into one vault balance
rejecting invalid coin colors
partial withdrawal
full withdrawal and balance removal
rejecting withdrawal when the witness secret does not match an existing vault
rejecting withdrawal when a stolen witness secret is used from a different public key

The accumulation test is important. The core behavior is not only accepting deposits, but merging multiple deposits into one running vault balance:

simulator.deposit(100n);
simulator.deposit(200n);

const { item: vault } = getOnlyVault(simulator);

expect(vault.balance).toBe(300n);

Run:

bun run test:run

Expected result:

Test Files  1 passed (1)
Tests       9 passed (9)

What You Learned

In this tutorial, you learned how to:

start a Compact project with Bun
add fast and full compile scripts
write exported Compact circuits
define ledger maps
model a vault position with a struct
use witness functions for private state
generate a commitment-based user ID
receive shielded tokens with receiveShielded
store shielded coin balances with insertCoin
merge new deposits with mergeCoinImmediate
send withdrawals with sendShielded
manage returned change manually
test the contract with generated TypeScript bindings

Next Improvements

This vault is intentionally minimal. If you want to extend it, try:

adding zero-amount checks
supporting multiple vaults per user
extracting repeated balance update logic into helper circuits
adding events or richer metadata
building a frontend for deposit and withdraw actions
supporting only one approved asset instead of multiple coin colors
moving per-user balances into private state and storing only commitments on-chain

Closing

This vault dApp is a compact example of how Midnight smart contracts can combine private state, shielded assets, and public ledger updates.

If you are learning Compact, this is a good project to study because it touches the pieces you need for many real dApps: identity derivation, token transfer, state management, and testing.

GitHub link: https://github.com/codeBigInt/midnight-simplified-tutorial-dapps/tree/main/vault-dapp

JOURNEY INTO BLOCKCHAIN DEVELOPMENT THE EASY WAY

Elliot lucky — Sat, 01 Nov 2025 15:28:53 +0000

Hmmm, thank goodness you found this blog post. I’m sure by now you’ve toured half the internet searching for an easier way to get started in the blockchain industry as a developer. I get it looks complicated, sounds technical, and can feel overwhelming trying to piece everything together.

That’s exactly why I decided to share my experience to give you a simpler, clearer path into blockchain development and hopefully inspire your own journey.

Like Isaac Newton once said, “If I have seen further, it is by standing on the shoulders of giants.”

So before we dive into my personal story, let’s first understand what blockchain really is, and why it was invented in plain, beginner-friendly terms.

🔗 WHAT AND WHY BLOCKCHAIN?

Let’s take a scenario.
When you think of a bank, you think about monetary records of people who own accounts i.e., a ledger or journal, although a bit advanced these days with the invention of computers. These ledgers are owned and controlled by these banks. What happens if there’s a fire outbreak and all the financial records become historical ashes (not the cricket trophy, LOL 🤭)? I mean actual ashes.

Of course, we would not know who owns what. This is one of the reasons blockchain was invented a “distributed/decentralized ledger,” not owned or controlled by a single entity or enterprise.

These ledger records are distributed in the sense that they are stored on several computers around the globe called “nodes,” each having the same copy of the ledger.

In today’s world where ledgers are no longer used, it can be likened to a distributed or decentralized database.

But you may ask, why then is it called a blockchain and not just a decentralized database? Well, instead of storing user transactions or data in rows and columns as banks would do, transactions or data are bundled into small units called “blocks.” And unlike pages of a ledger linked together by glue and referencing each other in the head of the documents, each block is linked together by “hashes”; a fixed-length string that represents the data contained in the block and the next block combined together.

Enough of the jargon. Back to my experience diving into blockchain development. There are different blockchains, each solving a particular problem e.g., Bitcoin (removes the need for financial intermediaries like banks), Ethereum (eliminating the need for third parties in agreements through smart contracts), Cardano, Midnight (a privacy-centered blockchain), Avalanche, etc.

🤯 MY EXPERIENCE DEVELOPING ON ETHEREUM

For me, I started with Ethereum not because it was easy to learn, but because it was one of the most popular at the time and still is. Development on Ethereum introduced the concept of smart contracts, which is now an integral part of every blockchain.

In fact, smart contracts are what make modern blockchains usable. They are “self-executing” programs or code you write and deploy to the blockchain just like you would on AWS or Vercel with an application you just finished building. They execute themselves when the conditions you define within the contract are met. Like any other application (web or mobile), they have to be coded using a programming language. For Ethereum, I had to learn “Solidity.”

Solidity was difficult for me to catch up with, as it had a syntax (language writing pattern) that looked like C++ and JavaScript combined. Being a newbie in programming who only had knowledge of web development-centered languages like JavaScript, a bit of TypeScript (a subset of JavaScript), and frontend frameworks like React as at the time, I became overwhelmed.

I had to learn how to manage memory usage while writing Solidity code, structs, maps, etc. After a while, I knew I was not just ready for it and had to go back to where I came from 😄, web development. Still with the intent of learning blockchain, but with a failed attempt.

💡WHAT CHANGED?

Eventually, I came across a sidechain built on the Cardano blockchain called Midnight. Unlike every other blockchain, its language is so easy to learn, and it solves a key pain point in blockchain, decentralization without compromising users’ privacy. On most blockchains, everything is public, including user assets, details, and confidential information.

Midnight blockchain solves this by ensuring users’ private data is secure and allowing them to choose when to share their info, while still maintaining the decentralized nature expected from every blockchain.

Most importantly, its smart contract language is really easy to learn. It’s just like TypeScript. That’s to say, if you know TypeScript, you can dive straight in and start developing on Midnight. The language is called Minokawa (formerly Compact). It uses data types similar to arrays, objects, functions, and strings in TypeScript. Except that it differs slightly in how you write them.

This was when I knew I had found the right spot for me to master and experience what developing on the blockchain feels like without having to learn an entirely strange programming language. Believe me, in less than 3 months I had learned how to write complex smart contracts just because I knew TypeScript. Its ecosystem is enriched with great minds building and collaborating on both individual projects and hackathons (two of which I have won) all in the quest to improve the ecosystem.

WHAT I RECOMMEND ⭐⭐⭐⭐⭐

While choosing a blockchain to start developing on depends on the programming languages and concepts one is already familiar with, I would recommend Midnight Blockchain.

Why? Because if you’re someone like me coming from a web or mobile development background, you already know JavaScript. This means you can easily learn TypeScript in less than a month and transition into blockchain development on Midnight.

Everyone’s blockchain journey is different, but the key is to start where you are and build from what you already know.

That’s what helped me find my path and hopefully, this helps you find yours too.

Want to checkout Midnight? Here’s a glimpse of what it feels like writing smart contracts!
https://docs.midnight.network/develop/reference/compact/writing

Stay curious. Keep building. The future is decentralized. ✨