DEV Community: Elliot lucky

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. ✨