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

This article is the written companion to my Midnight Simplified video:

https://www.youtube.com/watch?v=MCumZemoX5c

In the video, we 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: creating positions, receiving shielded tokens, tracking balances, 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 vault contract where a user can:

create a vault position
choose the coin color that vault accepts
deposit a shielded coin into the 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

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

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

In the video description, I also mention linking to the updated setup resources because the Midnight toolchain has had upgrades. Make sure your Compact compiler version matches the language version used in this project.

This contract uses:

pragma language_version >= 0.22.0;

That goes with the newer Compact compiler version used in the tutorial.

You will also want the Compact standard library documentation open because we use shielded token helpers such as:

receiveShielded
sendShielded
mergeCoinImmediate
insertCoin
ownPublicKey
kernel.self

Step 1: Create the Project

In the video, we start from a blank 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 language pragma:

pragma language_version >= 0.22.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

Before defining all the state, it is useful to outline the main behavior of the vault.

The vault needs three exported circuits:

export circuit createVault(
    _color: Bytes<32>
): []{
}

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

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

These are the three user-facing actions:

createVault: create a vault position
deposit: deposit shielded tokens into the contract
withdraw: withdraw shielded tokens from the contract

At this point in the video, we compile early 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>;
    createdAt: Uint<64>;
    coinColor: Bytes<32>;
}

The vault stores:

balance: the amount deposited into the vault
createdAt: when the vault was created
coinColor: the token color this vault accepts

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 deposits the same asset type they selected when creating the vault.

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.

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

The video spends time on this because it matters for token transfers.

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 Witness Functions

We do not want to store the user's public wallet address as the vault owner. That would defeat the purpose of building a shielded contract.

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

Declare the witnesses:

witness getSecretKey(): Bytes<32>;
witness getCurrentTime(): Uint<64>;

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

getCurrentTime() lets the contract set the vault creation timestamp.

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

The current tutorial code uses "vaul: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: Implement createVault

Inside createVault, derive the user ID:

const newUserId = generateUserId(disclose(getSecretKey()));

Because the secret key comes from a witness, we disclose it before using it in the circuit.

Next, make sure this user does not already have a vault:

assert (!vaults.member(newUserId), "Already exist");

Then create the empty vault:

const emptyVault = Vault {
    balance: 0,
    coinColor: disclose(_color),
    createdAt: disclose(getCurrentTime())
};

Finally, insert it:

vaults.insert(newUserId, emptyVault);

The complete circuit:

export circuit createVault(
    _color: Bytes<32>
): []{
    const newUserId = generateUserId(disclose(getSecretKey()));

    assert (!vaults.member(newUserId), "Already exist");

    const emptyVault = Vault {
        balance: 0,
        coinColor: disclose(_color),
        createdAt: disclose(getCurrentTime())
    };

    vaults.insert(newUserId, emptyVault);
}

Run a quick compile:

bun run test-compile

During the video, one common issue appears here: forgetting semicolons. Compact expects semicolons at the end of statements, and the compiler will point you to the line that needs fixing.

Step 10: Implement deposit

The user deposits a shielded coin:

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

Before receiving the token, check that the user has a vault:

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

Then make sure the deposited coin is the right type:

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

Now receive the shielded 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.

Finally, update the vault accounting balance:

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

The complete deposit circuit:

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

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

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

    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 updatedVault = Vault {
        ...vault,
        balance: (vault.balance + coin.value) as Uint<128>
    };

    vaults.insert(userId, updatedVault);
}

Compile 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()));

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");

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 calling the circuit, so we use:

left<ZswapCoinPublicKey, ContractAddress>(ownPublicKey())

ownPublicKey() returns the ZswapCoinPublicKey of the end user creating the transaction.

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);
}

The auto-generated subtitle says is_sum in this part, but the contract code uses is_some. Follow the generated Compact type in your local compiler output if this API changes.

Then reduce the user's vault balance:

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

vaults.insert(userId, updatedVault);

The complete withdraw circuit:

export circuit withdraw(_amount: Uint<128>): []{
    const amount = disclose(_amount);
    const userId = generateUserId(disclose(getSecretKey()));
    assert (vaults.member(userId), "You have no vault position");

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

    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);
}

Run the compile script again:

bun run test-compile

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

ownPublicKey()

Step 12: Implement the TypeScript Witnesses

The Compact file declares witnesses. TypeScript provides their runtime implementation.

Create src/witness.ts:

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

export interface VaultPrivateState {
    secreteKey: Uint8Array
}

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

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

    getCurrentTime: (
        {privateState}: WitnessContext<Ledger, VaultPrivateState>
    ): [VaultPrivateState, bigint] => {
        return [privateState, BigInt(Date.now())]
    },
}

The witness returns a tuple:

[privateState, witnessValue]

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

One cleanup you can make later is renaming secreteKey to secretKey. The current project uses secreteKey, so the article keeps that spelling where it reflects the code.

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:

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

The tests cover:

deploying with empty ledgers
creating a vault
rejecting deposits before vault creation
accepting valid deposits
rejecting invalid coin colors
partial withdrawal
full withdrawal and balance removal

Run:

bun run test:run

Expected result:

Test Files  1 passed (1)
Tests       7 passed (7)

Full Contract

Here is the complete src/vault.compact:

pragma language_version >= 0.22.0;
import CompactStandardLibrary;

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

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

witness getSecretKey(): Bytes<32>;
witness getCurrentTime(): Uint<64>;

export circuit createVault(
    _color: Bytes<32>
): []{
    const newUserId = generateUserId(disclose(getSecretKey()));

    assert (!vaults.member(newUserId), "Already exist");

    const emptyVault = Vault {
        balance: 0,
        coinColor: disclose(_color),
        createdAt: disclose(getCurrentTime())
    };

    vaults.insert(newUserId, emptyVault);
}

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

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

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

    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 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()));
    assert (vaults.member(userId), "You have no vault position");

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

    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
    ]);
}

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 private 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 create, deposit, and withdraw actions
supporting only one approved asset instead of multiple coin colors
improving naming before production use

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.

Watch the full tutorial video here:

https://www.youtube.com/watch?v=MCumZemoX5c
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. ✨