Intro

Hello, friend 👋

My name is Pavel, aka kode-n-rolla.
I am a Security Engineer, and today I want to share my engineering view of a Solana escrow program. I named it Escrovia.

Escrow programs are a good way to understand what makes Solana development different from more conventional backend work.

At first glance, an escrow looks simple: one user locks token A, another user pays token B, and the program releases the locked funds. The interesting part is not the high-level business logic. The interesting part is how the program models authority, account relationships, token ownership, and invalid account combinations.

On Solana, this simple idea becomes a great exercise in account architecture.

To build escrow correctly, we need to think about PDAs, token vaults, authority checks, account constraints, signer validation, and safe state transitions.

That is why I built Escrovia - a compact Anchor-based escrow program focused on clean account design and predictable instruction flow.

Let’s dive in. 🥽

Why Split the Program Into Instructions

First of all lets talk about projects structure.

Anchor examples often keep everything inside lib.rs. That is fine for a short demo, but it becomes harder to maintain once the program starts to grow.

Escrovia separates each instruction into its own module:

programs/escrovia/src/
├── lib.rs
├── state.rs
├── errors.rs
└── instructions/
    ├── mod.rs
    ├── make.rs
    ├── take.rs
    └── refund.rs

This structure keeps each instruction focused on a specific flow:

• make creates an escrow offer and locks the maker's tokens.
• take completes the swap and releases the vault tokens to the taker.
• refund lets the maker cancel the offer before it is taken.

The benefit is not only readability. Each instruction has its own account graph, constraints, CPI calls, and failure modes. Keeping them separate makes it easier to reason about one boundary at a time.

The program entrypoints in lib.rs stay intentionally small:

pub fn make(
    ctx: Context<Make>,
    seed: u64,
    receive: u64,
    amount: u64,
) -> Result<()> {
    instructions::make::handler(ctx, seed, receive, amount)
}

pub fn take(ctx: Context<Take>) -> Result<()> {
    instructions::take::handler(ctx)
}

pub fn refund(ctx: Context<Refund>) -> Result<()> {
    instructions::refund::handler(ctx)
}

This pattern turns lib.rs into a routing layer. The actual instruction logic lives next to the account context that validates it.

The Escrow Flow 🌊

The escrow has three main states from a user perspective:

1. A maker creates an offer.
2. A taker accepts the offer.
3. The maker refunds the offer if it has not been taken.

In the make flow, the maker deposits token A into a vault controlled by the escrow PDA. The program stores the expected token B mint and amount in the escrow state account.

In the take flow, the taker sends token B to the maker. If that transfer succeeds, the program signs as the escrow PDA and releases token A from the vault to the taker.

In the refund flow, only the maker can cancel the escrow. The program returns token A from the vault to the maker and closes the escrow accounts.

The important detail is that the program does not rely on an off-chain agreement. The terms are stored on-chain in the escrow state.

#[account]
#[derive(InitSpace)]
pub struct Escrow {
    pub seed: u64,
    pub maker: Pubkey,
    pub mint_a: Pubkey,
    pub mint_b: Pubkey,
    pub receive: u64,
    pub bump: u8,
}

This state account is the source of truth for the swap. It records who created the escrow, which mint was deposited, which mint is expected in return, how much should be paid through the receive field, and which bump is required to sign as the PDA.

Modeling Accounts as a Security Boundary

On Solana, users provide accounts to instructions. That means a program must not only execute logic; it must verify that the supplied accounts form the expected relationship graph.

For an escrow, that graph includes:

• the maker signer;
• the escrow state PDA;
• the maker's token account for token A;
• the vault token account controlled by the escrow PDA;
• the taker's token account for token B;
• the maker's token account for token B;
• the token mints;
• the token program and associated token program.

This is why Anchor account constraints matter. They are not decorative boilerplate. They define which combinations of accounts are valid and which combinations should fail before any funds move.

For example, the escrow PDA can be derived from a stable set of seeds:

seeds = [b"escrow", maker.key().as_ref(), seed.to_le_bytes().as_ref()]

That derivation gives the program a deterministic address for each maker and seed pair. It also prevents two escrow offers from using the same maker and seed without colliding on the same state account.

The vault is modeled as an associated token account where the authority is the escrow PDA:

associated_token::mint = mint_a,
associated_token::authority = escrow

This matters because the vault should not be controlled by the maker or the taker. It should be controlled by program logic through the PDA.

PDA-Controlled Vaults

The vault is where the maker's deposited token A is held while the escrow is open.

The program cannot own a private key, so it cannot sign like a normal wallet. Instead, it uses a PDA as the vault authority. When the program needs to move funds out of the vault, it signs a CPI with the same seeds used to derive the PDA.

Conceptually, the signer seeds look like this:

let signer_seeds: &[&[&[u8]]] = &[&[
    b"escrow",
    self.maker.to_account_info().key.as_ref(),
    &self.escrow.seed.to_le_bytes()[..],
    &[self.escrow.bump],
]];

Those seeds allow the program to authorize token transfers from the vault without ever needing a private key.

This is one of the core ideas in Solana escrow design:

The vault is not trusted because it exists. It is trusted because its mint, authority, and address are constrained to match the escrow state.

If the instruction accepted any vault account without validation, a malicious transaction could try to route funds through an unrelated token account. The account constraints prevent that.

Instruction Responsibilities

Each instruction has a narrow responsibility.

Make

make initializes a new escrow offer.

It is responsible for:

• creating the escrow state PDA;
• creating or validating the vault token account;
• transferring the maker's deposited token A into the vault;
• storing the escrow terms on-chain.

The most important checks are that the maker owns the source token account, the deposited mint matches mint_a, and the vault is controlled by the escrow PDA.

Take

take completes the swap.

It is responsible for:

• transferring token B from the taker to the maker;
• transferring token A from the vault to the taker;
• closing the vault token account;
• closing the escrow state account.

The order matters. The taker should only receive token A after the maker receives token B. The program also needs to ensure that the token accounts match the mints stored in the escrow state.

Refund

refund cancels an open escrow.

It is responsible for:

• allowing only the maker to cancel;
• transferring token A from the vault back to the maker;
• closing the vault;
• closing the escrow state account.

This instruction is intentionally smaller than take, but it is still security-sensitive. A refund path that does not validate the maker or vault correctly can become a way to drain locked funds.

Testing the Account Graph

The happy path proves that the program works when all accounts are correct and every participant behaves honestly.

That is necessary, but not sufficient.

For Solana programs, many bugs live in invalid account combinations. A transaction can pass accounts that are structurally valid Solana accounts but semantically wrong for the instruction.

Escrovia's tests cover the main flows:

• creating an escrow;
• taking an escrow;
• refunding an escrow.

They also cover negative cases:

• refund from a non-maker;
• take with insufficient token B balance;
• make with zero deposit amount;
• make with zero receive amount;
• take with the wrong vault;
• refund with the wrong vault;
• make with a token account not owned by the maker;
• duplicate escrow creation with the same maker and seed.

These tests are not only about reaching code coverage numbers. They check whether the account model rejects transactions that should not be valid.

A useful pattern in the tests is to assert that failed transactions do not mutate important state:

const escrowAccount = await provider.connection.getAccountInfo(escrowPda);
expect(escrowAccount).to.not.be.null;

const vaultAccount = await getAccount(provider.connection, vaultAta);
expect(Number(vaultAccount.amount)).to.eq(depositAmount);

This verifies that the escrow and vault remain locked after an invalid attempt.

What the Implementation Reinforced

The main lesson from building Escrovia is that token transfer logic is only one part of the program.

The more important part is the account model:

• Which account owns the state?
• Which PDA controls the vault?
• Which token mint belongs to each token account?
• Which signer is authorized to perform the action?
• Which accounts should be closed after the escrow is resolved?

Getting these relationships right makes the instruction logic smaller and easier to audit.

The second lesson is that modularity pays off early. Even in a compact program, splitting make, take, and refund into separate instruction modules keeps the implementation easier to read, test, and refactor.

The third lesson is that tests should include hostile account combinations. A program that only passes happy-path tests may still accept invalid accounts in production-like scenarios.

Conclusion

Escrovia is a compact escrow program, but it touches several important Solana development patterns:

• PDA-derived state;
• PDA-controlled token vaults;
• associated token account constraints;
• CPI signing with seeds;
• account closing;
• positive and negative integration tests.

For escrow-like programs, the core engineering task is not just moving tokens. It is defining and enforcing the account graph that makes those token movements safe.

Once that graph is clear, the instruction logic becomes much easier to reason about.

Outro

Thank you for your time, dear reader. 🤜🤛

I hope this article gave you something useful - whether it was a better understanding of Solana escrow architecture, PDA-based account design, token custody, or simply another perspective on how small programs can still contain real engineering decisions.

If you want to follow my work, discuss Solana security, or share feedback, you can find me here:

GitHub 🧑‍💻
GitLab 🥼

LinkedIn 💼

Medium and Hashnode ✍️

X (aka Twitter) 💬

Stay curious 🔬.

Stay cyber safe 🛡️.