Forem: Claude Barde

Introduction to the FungibleToken contract on Midnight

Claude Barde — Thu, 11 Sep 2025 14:35:44 +0000

Introduction to the FungibleToken contract on Midnight

Midnight is a privacy-first blockchain designed to bring privacy to decentralized applications. It achieves this through zero-knowledge proofs, programmable data protection, and developer-friendly tools like Compact, a TypeScript-based DSL (Domain-Specific Language) for writing privacy-aware smart contracts.

OpenZeppelin is renowned in the Ethereum ecosystem for its battle-tested smart contract libraries, which have secured trillions in on-chain value. Recently, OpenZeppelin partnered with Midnight to bring comparable tooling to the Compact ecosystem, adapting familiar standards like ERC-20 into privacy-preserving variants.

In the Ethereum world, the ERC-20 standard defines a fungible token with public ledger functions like balanceOf, transfer, approve, etc. It exposes transaction data transparently and lacks built-in privacy. The FungibleToken contract on Midnight draws inspiration from this, but operates within Midnight’s zero-knowledge, selective-disclosure framework.

Fungible tokens are a cornerstone of the blockchain ecosystem, representing digital assets that are interchangeable – much like traditional currency. On various blockchains, these tokens power a wide array of applications, from facilitating seamless transactions and enabling decentralized finance (DeFi) protocols to representing ownership in digital communities and driving the mechanics of in-game economies.

Unlike unique non-fungible tokens (NFTs), the value of one fungible token is identical to another of the same type, making them ideal for use cases requiring divisibility and ease of exchange. Their widespread adoption underscores their importance in building liquid and interconnected digital economies.

In this article, you'll learn about the core features of the contract, including how it manages ledger state variables, its key entry points and circuits for operations like minting, burning, and transferring tokens, and the essential safety and utility functions provided by the Utils and Initializable modules.

By understanding how these components fit together, you’ll gain insight into how the FungibleToken contract balances fungibility, usability, and privacy, providing an essential building block for privacy-preserving DeFi, identity, and tokenized assets on Midnight.

Features of the FungibleToken Contract

The FungibleToken contract on Midnight utilizes ledger state variables to keep track of balances, allowances, total supply, name, symbol, and decimals. Its functionality is exposed through "circuits" (entry points) like Mint, Burn, Transfer, Approve, TransferFrom, and Initialize, all of which enforce specific zero-knowledge validated transitions and maintain the integrity of the token's state.

1. Ledger State Variables

In Compact, the contract defines a structured state storing token balances and allowances—similar to ERC-20. The _balances map keeps track of the users’ token balances and is updated when a transfer occurs. The _allowances map keeps track of the permission given to specific users to spend tokens on behalf of another user:

export ledger _balances: Map<Either<ZswapCoinPublicKey, ContractAddress>, Uint<128>>;
export ledger _allowances: Map<Either<ZswapCoinPublicKey, ContractAddress>, Map<Either<ZswapCoinPublicKey, ContractAddress>, Uint<128>>>;

These values live in the contract's ledger and are updated through transactions sent to the contract.

There are other values in the ledger that are set when the contract is deployed:

export ledger _totalSupply: Uint<128>;
export sealed ledger _name: Opaque<"string">;
export sealed ledger _symbol: Opaque<"string">;
export sealed ledger _decimals: Uint<8>;

These values provide different information about the token managed by the contract, its total supply, its name, its symbol, and its decimal (for display).

2. Entry Points and Circuits

In Compact, entry points are defined as circuits (akin to Solidity functions), each modelling a zero-knowledge validated transition. The difference between a circuit entry point and a circuit is that the entry point is callable via a transaction, while the non-entry point circuit is internal. Core circuits include:

Mint / Burn (to mint new tokens or burn existing tokens).
Transfer: to move tokens between addresses.
Approve, TransferFrom: standard ERC-20-style delegation mechanisms.
Initialize: via the Initializable module for contract setup.

Each circuit enforces necessary constraints — for example, ensuring sufficient balance, managing allowance decrements, and preserving total supply.

In the next step of the contract lifecycle, the different metadata stored in the ledger of the contract are safely initialized.

Initialization & metadata

The following circuits define the essential setup and retrieval logic for the fungible token metadata and users’ balances, enforcing correct initialization.

initialize(name_, symbol_, decimals_)

One-time setup. Calls Initializable_initialize(), then stores the (disclosed) name, symbol, and decimals. Every other public circuit asserts that the contract is initialized first.
name() / symbol() / decimals() / totalSupply()

Simple getters that first assert initialized, then return the sealed (read only) ledger values.
balanceOf(account)

Safe map lookup that returns 0 if the account isn’t present (to prevent contract failure if the key is absent).

The transfer family

The FungibleToken contract's transfer circuits manage token movement. Key circuits include: transfer for safe user-initiated transfers, _unsafeTransfer for internal token movement, _transfer for administrative transfers, _unsafeUncheckedTransfer for low-level token movement, and _update as the central accounting function for all token operations.

These are split into safe and unsafe variants because sending to contract addresses is currently disallowed (until contract-to-contract interactions are supported).

“Safe” circuits enforce that policy; “unsafe” ones let you bypass it—explicitly marked as dangerous in comments.

transfer(to, value) → Boolean

Safe user-initiated transfer: rejects if to is a ContractAddress. Internally, it just forwards to the unsafe variant after the check.
_unsafeTransfer(to, value) → Boolean

Owner is the caller (left(ownPublicKey())). Moves value using the unchecked internal mover, then returns true.
_transfer(from, to, value) → []

Admin/extension hook that moves tokens from an arbitrary from (not necessarily the caller). Still enforces the “no contracts as to” rule and then uses the same mover underneath.
_unsafeUncheckedTransfer(from, to, value) → []

The low-level mover checks that neither side is the zero/burn address and then delegates the actual accounting to _update.
_update(from, to, value) → []

Central accounting function used by all mint/burn/transfer paths. It’s an internal circuit; it cannot be called via a transaction.
- If from is zero, the mint circuit is called, it asserts no uint128 overflow, and increases _totalSupply.
- Else, it deducts from from balance (or reverts on insufficient funds).
- If to is zero, the burn circuit is called, and it decreases _totalSupply.
- Else, it adds to to balance. This single function guarantees the invariants for every movement of value.

The "transfer family" circuits ensure secure token movement, with "safe" variants disallowing transfers to contract addresses and "unsafe" variants providing lower-level control.

This leads us to explore how allowances function, enabling delegated token spending.

Allowances (approve / spend / transferFrom)

This section details the allowance mechanisms within the FungibleToken contract, which enable users to delegate spending permissions to other addresses. These circuits facilitate secure, approved transfers on behalf of an owner without directly exposing their private keys.

allowance(owner, spender)

Read the nested _allowances map, returning 0 when keys are missing (no revert).
approve(spender, value) → Boolean

The owner is the caller. Forwards to _approve(owner, spender, value) and returns true.
transferFrom(from, to, value) → Boolean

Safe delegated transfer: enforces the “no contract receiver” rule, then defers to _unsafeTransferFrom.
_unsafeTransferFrom(from, to, value) → Boolean

The spender is the caller. First spends allowance via _spendAllowance(from, spender, value), then moves value using _unsafeUncheckedTransfer. Returns true.
_approve(owner, spender, value) → []

It ensures that both the owner and the spender are valid, creates the owner’s entry in the map if needed, and then writes the allowance. (This mirrors OZ’s ERC-20 pattern of public approve() → internal _approve().)
_spendAllowance(owner, spender, value) → []

It deducts from the allowance unless it’s “infinite.” The implementation treats MAX_UINT128 as infinite: if currentAllowance == MAX, it doesn’t decrement; otherwise, it asserts currentAllowance ≥ value and writes back currentAllowance - value.

This is important because it supports “no-friction approvals” by letting apps set MAX once.

So, we just covered how allowances let people delegate token spending—basically, giving others permission to move their tokens. Up next, we'll dive into how we create and delete tokens in the contract.

Minting and burning

Here's how the FungibleToken contract handles making and destroying tokens. We'll dive into the _mint and _burn functions, showing what they do and how they link up with the main accounting system.

_mint(account, value) (safe) → []

It forbids minting to a contract address (same contract-to-contract restriction), then forwards to _unsafeMint.
_unsafeMint(account, value) → []

It validates the receiver’s address, then calls _update(burnAddress(), account, value)—i.e., mint is modelled as a transfer from the burn/zero address.
_burn(account, value) → []

It validates the sender’s address, then calls _update(account, burnAddress(), value)—i.e., burn is a transfer to the burn/zero address.

Note: The actual notion of “zero/burn” address is standardized in the Utils module; you can also see helpers like Utils_isKeyOrAddressZero and Utils_isContractAddress.

Because mint and burn also route through _update, total supply is adjusted in exactly one place, and the same safety checks apply across all flows (including the uint128 overflow check on mint).

The mint and burn circuits, by using the _update function, make sure the total supply adjustments are always consistent and that all token flows get the same safety checks.

Now, let's dive into the extra safety and utility stuff that the Utils and Initializable modules bring to the table.

Safety & utility glue (from `Utils` and `Initializable`)

This section explores how the Utils and Initializable modules provide essential safeguards and helpful functionalities. These components are vital for ensuring the contract's integrity and enabling secure, well-managed operations.

Initialization guards: The Initializable_initialize and Initializable_assertInitialized functions serve as crucial initialization guards within the Initializable contract. These safeguards ensure that a contract's state is properly set up only once and that subsequent operations only proceed if the contract has been correctly initialized. Every circuit that interacts with or modifies the contract's state is designed to invoke the assert function, reinforcing the integrity of the initialization process.
Address helpers:
- Utils_isContractAddress(either) distinguishes user keys from contract addresses.
- Utils_isKeyOrAddressZero(either) detects the zero/burn address used in _update, _unsafeUncheckedTransfer, etc. These support the temporary “no contract receiver” policy and zero-address checks.

The Utils and Initializable modules provide crucial safety and utility functions, ensuring the contract's proper setup and secure operation. Now, let's look at how all these different parts of the FungibleToken contract work together.

How the pieces fit together

This part shows how everything in the FungibleToken contract is hooked up. Whether it's you sending tokens, someone else doing it for you, or tokens being created or destroyed, it all funnels through a few key functions and ultimately lands in the main _update function to keep track of everything.

User transfer:

transfer → (safe check) → _unsafeTransfer → _unsafeUncheckedTransfer → _update (balances/supply)
Delegated transfer:

transferFrom → (safe check) → _unsafeTransferFrom → _spendAllowance → _unsafeUncheckedTransfer → _update
Mint/Burn:

_mint/_unsafeMint or _burn → _update (with zero/burn address on one side)

This section illustrates how various token operations, from user transfers to minting and burning, ultimately funnel through the central _update function for consistent accounting. Now, let's summarize the key takeaways of the FungibleToken contract on Midnight.

Conclusion

The FungibleToken Compact contract on Midnight is a privacy-aware reimagining of the ERC-20 standard. It maintains the familiar token interfaces—balances, transfers, approvals—but encodes them as ZK-validated circuits within Compact, enabling private, verifiable execution. The contract’s state and logic are shielded by design, exposing only proofs rather than raw data to the blockchain.

The ERC-20 standard revolutionized the crypto landscape by providing a common framework for creating and managing digital assets, fostering interoperability, and accelerating the growth of decentralized applications. For Midnight, an ERC-20-based token is crucial as it leverages this established standard while integrating ZK-privacy, offering a familiar yet enhanced experience for developers and users seeking both functionality and confidentiality.

This model contrasts sharply with ERC-20 on Ethereum, where all token movements and balances are fully transparent. Here, Midnight allows selective disclosure: users and applications choose what to reveal. The FungibleToken contract thus balances fungibility, usability, and privacy—providing an essential building block for privacy-preserving DeFi, identity, and tokenized assets on Midnight.

Links

Delve deeper into the code, contracts, and comprehensive documentation to enhance your understanding and development skills. These resources are invaluable for building robust and innovative solutions.

FungibleToken contract: FungibleToken.compact on Github
OpenZeppelin documentation: docs.openzeppelin.com
ERC20 standard: ethereum.org
Midnight docs: Midnight Developer Documentation
Do you have any questions?: Midnight Forum

Get Married on the Blockchain!

Claude Barde — Fri, 22 Mar 2019 07:42:22 +0000

Or how the blockchain can also revolutionize our relationships…

Since the moment I heard about it, I have always been fascinated by the huge possibilities that smart contracts give us and I feel that they are still underestimated.

I started getting interested in Bitcoin almost two years ago but it's only a few months ago I discovered the Ethereum blockchain and Solidity. Since then, I haven't been able to stop myself from reading everything I can about the subject. I subscribed to mailing lists to receive articles about Ethereum and Solidity directly in my mailbox, I often take a peek at the Solidity docs and I read countless tutorials about the subject.

However, it looks like outside big companies, there aren't a lot of people out there who try to use the Ethereum blockchain in a more "disruptive" way. Most of the tutorials teach how to create ERC20 tokens or voting systems. I often let my mind wander and imagine what we could achieve if the blockchain would replace our governments. Which tasks could smart contracts allow us to take back and own again? That's how the idea of writing marriage certificate smart contracts came to me. After all, it is something relatively simple: two human beings want to be wed (for better or for worse), they register their union in front of an authority and they go back to the same authority for instance when they need to prove their marriage or when they want to divorce.

In real life, a marriage is a real challenge and people often end up wasting a lot of time and money. A smart contract can help them get married (or divorced) in a matter of seconds for a few cents. The immutability of the blockchain allows making sure the marriage certificate is not altered beyond its inner functions and makes it available anywhere at any time.

This is how the idea of celebrating marriages on the blockchain was born! Through the website, couples can create a smart contract that will store their personal identity information (like names, location and ID number) in an immutable fashion to be able to prove ownership of the certificate in a simple way, they can without efforts update the status of the marriage (a divorce would literally take seconds and a few cents to perform) and finally, the design of the smart contract allows couples to use the certificate to store common funds in two different ways: a "joint account" where each spouse can freely deposit and withdraw money and a "savings account" where the agreement of both spouses is required before withdrawing funds.

I will describe below the code of the smart contract (available at this address), function after function, in order to give a better understanding of what it does but also to receive useful feedback :) It may also be useful for beginners as I was a few months ago to get a detailed walk-through of how a smart contract works.

The Marriage Certificate Factory

Every marriage certificate is created by a factory smart contract that is in charge of setting the right state with the right data and savings the certificates addresses. As it is customary, the smart contract starts with the version pragma:

pragma solidity ^0.5.0;

The smart contract uses the latest version of Solidity compared to a lot of smart contracts written in the fourth version.

contract MarriageCertificateCreator {
    MarriageCertificate[] public certificates;
    address payable public owner;
    uint public certificateFee;
    string[3] public lastMarriage;

This is the contract declaration. It creates four state variables: a certificates variable (a dynamic array containing values of type "MarriageCertificate") which ultimately will contain the addresses of every certificate created, an owner variable (to use various functions of the smart contract), a certificateFee variable (an unsigned integer representing the fee in wei) and a lastMarriage variable (an array of 3 strings that will hold the names and location from the last registered certificate).

constructor() public {
    owner = msg.sender;
    certificateFee = 100000000000000000 wei;
}

The constructor is pretty straight forward, it saves the owner's address (mine) and sets the fee for the creation of a new marriage certificate to 0.1 ether. This fee can be manually updated in another function.

event NewCertificateCreated(
    MarriageCertificate newCertificateAddress, uint numberOfCertificates
);

This is the only event in this smart contract, it is emitted every time a new certificate is created and returns the address of the new contract and the total number of marriage certificates to the web3 interface.

The createNewCertificate function

This is where all the magic happens! The following function is in charge of receiving the data from the web3 interface, of validating them, of updating the state of the contract factory and obviously of creating the new marriage certificate.

You will find below a breakdown of the different parts of this function.

function createNewCertificate(
    string memory spouse1, string memory spouse2, address spouse2address, string memory location
    ) public payable {}

The function accepts 4 arguments:

The spouse1 variable is a JavaScript object in JSON format that contains various information about the first spouse (who is also the initiator of the marriage certificate). A JSON string is a better choice to store in the smart contract for multiple reasons: it allows to store different information in the future, it is easier to deal with in Solidity than other structures like array or structs, it is easier to fetch from the web3 interface (no need to convert it if it was, for example, a struct) and most of the information provided during the smart contract creation is not vital for its execution.
The spouse2 variable is also a JavaScript object in JSON format that holds the information relative to the second spouse. As the marriage certificate is created by one person, the second actor must validate the information later to make the marriage valid. The marriage stays in a permanent invalid state until the second spouse comes and approves the marriage.
The spouse2address variable contains the address of the second spouse who must approve the marriage. The two addresses will be stored independently as they are required to update the state of the newly created certificate.
The location variable is a Javascript object in JSON format holding the names of the city and the country chosen by the couple for the registration process.

MarriageCertificate newCertificate = 
    new MarriageCertificate(
        msg.sender,
        spouse1,
        spouse2,
        spouse2address,
        location
    );

The body of the function is responsible for passing down the arguments received earlier, the msg.sender being the address of spouse1. Note that whoever creates the marriage certificate will be considered as the first spouse, whatever value is passed in the spouse1 variable.
Note also that in Solidity 0.5, when you create a new smart contract from a smart contract, the value it returns is ultimately an address but it will be of type "NameOfCreatedSmartContract". This is also important to know as we will store these values in an array.

certificates.push(newCertificate);
lastMarriage = [spouse1, spouse2, location];
emit NewCertificateCreated(newCertificate, certificates.length);

The next lines of code are pretty straight forward: we push the address of the new certificate into the certificates array (whose values must be of type "NameOfCreatedSmartContract" as per Solidity 0.5), we update the lastMarriage variable so the value is always set to the last registered marriage and we emit an event that will be caught by the web3 interface.

The Marriage Certificate

The Marriage Certificate smart contract is a pretty simple one as it is mostly used to store immutable information about the two spouses, mutable information about the status of the marriage and common funds in two separate accounts, plus a couple of functions to deposit and withdraw the abovementioned funds.

A few variables are set during the creation of the contract as well as two event emitters: location, spouse1 and spouse2 will hold the information about the spouses and the place of registration. It should be noted that the ID numbers provided by the spouses during the certificate creation are encrypted client-side and a decryption key is provided, should the spouses have to prove they are the ones who registered the marriage.
The isValid variable is an array of 2 booleans representing the marriage status chosen by each spouse, spousesAddresses is an array of two addresses containing the spouses' addresses mostly used in require functions to make sure the status of the contract can only be modified by the two spouses.
The timestamp variable holds the creation timestamp and the accounts mapping keeps track of the amount of ether in the "joint" and "savings" account.
A withdrawRequestFromSavings struct will be created every time one of the spouses makes a withdrawal request from the savings account. The request is then saved in the withdrawRequests mapping.
Finally, the MarriageValidity event returns the isValid array and the NewWithdrawalRequestFromSavings event returns the newly created request.

The constructor

The constructor function is pretty standard:

It receives different information about the newlywed couple, stores it in the variables created earlier and set the "joint" and "savings" accounts to 0. The isValid variable is set to [true, false] as the marriage can only be valid after the second spouse approves it.

The contract state manipulations

The smart contract allows the spouses to update the status of the marriage as they wish. The status is calculated using a boolean operation with the && operator between the two values in the isValid array. This means that, for the marriage to be valid, both spouses must agree with it. A simple reading of the boolean values in the isValid array can also indicate which spouse agrees or disagrees with the marriage.

modifier onlySpouses {
        require (
            msg.sender == spousesAddresses[0] || msg.sender == spousesAddresses[1], "The contract status can only be changed by one of the spouses."
            );
        _;
    }

This modifier will be used a couple of times and makes sure that the person updating the state of the smart contract does it from one of the two addresses that were provided during its creation.

The changeMarriageStatus function does a simple boolean flip when one of the spouses asks for a change in the marriage status. Note that both spouses must set both values in the isValid array to true in order for the divorce to be effective.

The deposit/withdrawal functions

A smart contract being basically an Ethereum account with code, it would be a pity not to use this functionality :) To push it further, the marriage certificate is divided into two different accounts: a "joint" account and a "savings" account.
The "joint" account is an account where both spouses (or anyone else with an Ethereum address for that matter) can send ether and both spouses can withdraw as much as they want.
The "savings" account is an account where only the two spouses can send money to and in order to withdraw money, the initiator of the withdrawal must register a request that will have then to be approved by the second spouse.

Let's dive into the code:

The deposit function allows the spouses to deposit money through the web interface. It accepts 2 parameters: the amount to be added and the name of the account to increment. The onlySpouses modifier makes sure only the two spouses have access to this function.

As a safety measure, the contract verifies that the amount selected by the user is also the amount that was sent. The stringsAreEqual function checks the bytes32 variable and the contract decides to increment the joint or the savings account accordingly. The last assert function is there to check that whatever happens, the sum of the joint account and the savings account is always equal to the total balance of the contract.

Every change in balance that goes through the functions of the smart contract emits a LogBalance event with the total balance, the balance of the "joint account" and the balance of the "savings balance".

The withdraw function is a bit more intricate. None of the spouses is allowed to withdraw money from the savings account without the approval of the second one and this function must make sure it doesn't happen.
If one of them sends a transaction to withdraw ether from the savings account, a request is saved in the contract and a request ID is issued. The second spouse must use his/her own account address to approve the request.

First of all, the onlySpouses modifier ensures that no one other but the two spouses can withdraw money from the contract. The contract then checks if the requested amount doesn't exceed the balance in the selected account.
The first condition verifies the name of the selected account and checks the requested amount to be sure it doesn't exceed the balance of the account.

If the "joint" account is chosen, the result is straightforward: the amount is deducted from the balance and sent to the sender.

If the "savings" account is chosen, the contract creates a (pseudo) unique ID adding the current timestamp, the block difficulty and the block number. As it is very unlikely that two requests come exactly at the same time, this should suffice. A new struct of type withdrawRequestFromSavings is created and saved in the withdrawRequests mapping using the ID as a key. Once the new request is saved in the mapping, we emit an event to fetch the request ID in the web interface.

To finish, we check once again that the joint account balance and the savings account balance equal the total balance and the contract is reverted to its previous state if it isn't the case.
Now let's have a look at the function allowing the spouses to approve withdrawal requests from the savings account and sending the funds.

The approveWithdrawRequestFromSavings function takes the request ID as a parameter. The function can only be accessed by one of the spouses. The contract fetches the request from the mapping in storage and runs a few checks: by checking the timestamp and the amount, it makes sure the request exists (they will be equal to 0 by default if the request struct was not found), then it checks whether the requested amount is still available and whether the request is still pending (it wouldn't make sense to approve a request that's already approved!)

If the request is pending, the next condition ensures that the spouse approving the request is NOT the one who created it (users trying to approve a request they created themselves will trigger the revert function).
If everything is all right, the request is marked as approved (true), the requested amount is deducted from the savings account and sent to the spouse who initiated the request.

The pay function allows spouses to use the money in the joint account to pay for various expenses like bills. The function checks if the amount that is requested is available in the joined account before deducting it and sending it.
Once this is done, the function makes sure the total balance equals the joint account balance and the savings account balance.
In the end, a LogBalance event is emitted to update the user interface.

To conclude, it is worth mentioning the fallback function :

Any ether sent directly to the contract will be added to the joint account. Please note that the transaction will fail if around 42.000 gas is not provided.

Conclusion

I hope this article helped you understand the inner mechanics of a smart contract created to register marriages on the blockchain, to keep track of the marriage status, to manage a marital budget and to ease various processes involved in the bureaucracy of marriage.

Beyond the practical side of such a contract, it is also envisioned as a demonstration of how far the blockchain can push the limits of our centralized society and open the gates of a decentralized world where we will all take back the power to make decisions for ourselves!

Links

You can find the website here, the smart contract at this address or check the Github repository.

Forem: Claude Barde

Introduction to the FungibleToken contract on Midnight

Introduction to the FungibleToken contract on Midnight

Features of the FungibleToken Contract

1. Ledger State Variables

2. Entry Points and Circuits

Initialization & metadata

The transfer family

Allowances (approve / spend / transferFrom)

Minting and burning

Safety & utility glue (from Utils and Initializable)

How the pieces fit together

Conclusion

Links

Get Married on the Blockchain!

Or how the blockchain can also revolutionize our relationships…

The Marriage Certificate Factory

The createNewCertificate function

The Marriage Certificate

The constructor

The contract state manipulations

The deposit/withdrawal functions

Conclusion

Links

Safety & utility glue (from `Utils` and `Initializable`)