Hi, my name is Heorhii. In this article, I’ll guide you through one of the most important topics for building private apps on Aleo: how to handle public and private state. If you’ve worked with smart contracts on Ethereum, you're used to public-by-default data. Aleo flips that assumption and gives developers full control over what’s kept private and what can be made public.

Let’s explore how this works and how to use it in real-world scenarios.

Privacy on Aleo. Aleo is a layer-1 blockchain that uses zero-knowledge cryptography to provide privacy by default. That means your program inputs, outputs, and even user identity can be hidden on-chain unless you choose to reveal them.

In Aleo, developers work with two main types of state:

• Private state, stored as records

• Public state, stored using mappings

The platform allows you to switch between them based on your use case.

Storing private state with records. Records are encrypted pieces of program state that only the owner can view and modify. They are stored as ciphertext on-chain, but they can still represent anything: balances, identity data, permissions, or game assets.

A simple record might look like this:

record Balance {
  owner: address,
  amount: u64,
}

Records are tied to the user's address and only readable if you have the view key. That’s a special key that lets users share read-only access to their private data, without giving spending rights.

Storing public state with mappings. Mappings are key-value pairs stored on-chain and visible to anyone. They work like a simple database and are great for keeping data public, such as:

• Voting results

• Public leaderboards

• Token metadata

Example:

mapping votes: address => u8;

You can query this data using Aleo explorer or other blockchain tools.

Example: Mixing private and public state. Aleo lets you move between private and public state in your app. Here’s a simple program where we store the result of a sum in a record:

program sum.aleo {
  record sum {
    public owner: address,
    amount: u64,
  }

  transition main(public a: u64, b: u64) -> sum {
    let c: u64 = a + b;
    return sum {
      owner: self.caller,
      amount: c,
    };
  }
}

Here, a is public, b is private, and the output is stored in a record. Only the owner of that record can view it unless they share their view key.

Async programming for public state. When you update public mappings, you use async functions and Futures. Here’s how that looks:

program counter.aleo {
  mapping total: u8 => u64;

  async transition increment() -> Future {
    return update_count();
  }

  async function update_count() {
    let current: u64 = total.get_or_use(0u8, 0u64);
    let new: u64 = current + 1u64;
    total.set(0u8, new);
  }
}

Async functions are only executed after a proof is verified. Transition functions run first and return a Future. Then the network finalizes the state change.

More info you can find here:

https://developer.aleo.org/concepts/fundamentals/public_private

Calling async transitions from other programs. Let’s say one program calls another:

import counter.aleo;

program dashboard.aleo {
  mapping logs: u8 => scalar;

  async transition update_log(val: u8) -> Future {
    let update_future = counter.aleo/increment();
    return apply_log(val, update_future);
  }

  async function apply_log(val: u8, f: Future) {
    f.await();
    let hash: scalar = BHP256::hash_to_scalar(val);
    logs.set(val, hash);
  }
}

Notice how the Future is passed to an async function and await is used to ensure the call completes.

Private state in async transitions. When working with Aleo's async programming model, it's important to understand a key limitation: you can't create or spend private records directly inside async function blocks. This is because these functions are executed after the transaction has already been proven, which means they can't handle sensitive state updates that require zero-knowledge protection.

However, you can use private records inside transition and async transition functions. These run off-chain, generate the required proof, and are verified by the network before any state is finalized.

So, if you're working with public state, you'll use async function blocks with mappings. But if you're handling private state like encrypted records, stick to transition or async transition functions. Only the record owner can view this data, and only with their view key.

In short:

• Use mappings with async function for public state updates.

• Use records with transition or async transition when dealing with private data.

More info you can find here:

https://docs.leo-lang.org/guides/async

Real-world use case: voting. A great example is voting. You want your individual vote to remain private, but the total result to be public. Aleo’s hybrid model makes this possible.

“In elections, people want to vote, but they don’t want to show other people how they voted. The tally of the votes needs to be public to understand the outcome. Having private votes and public tallies ends up being a capable functionality in applications here.” — Howard Wu

This hybrid approach unlocks use cases that can't be built easily on Ethereum or Zcash.

Final thoughts. Aleo gives you full control over your application’s privacy. Whether you want to store state as encrypted records or readable mappings, you decide what the world can see.

By combining public and private states with zero-knowledge proofs and async execution, Aleo enables a new category of secure and scalable applications.

To know more about Aleo, join now!

• Aleo Twitter

• Aleo Discord

• Aleo Website

• List of Aleo and Leo code and resourses

Prepared by Colliseum

Hi, my name is Heorhii. In this article, I’ll guide you through one of the most important topics for building private apps on Aleo: how to handle public and private state. If you’ve worked with smart contracts on Ethereum, you're used to public-by-default data. Aleo flips that assumption and gives developers full control over what’s kept private and what can be made public.

Let’s explore how this works and how to use it in real-world scenarios.

Privacy on Aleo. Aleo is a layer-1 blockchain that uses zero-knowledge cryptography to provide privacy by default. That means your program inputs, outputs, and even user identity can be hidden on-chain unless you choose to reveal them.

In Aleo, developers work with two main types of state:

• Private state, stored as records

• Public state, stored using mappings

The platform allows you to switch between them based on your use case.

Storing private state with records. Records are encrypted pieces of program state that only the owner can view and modify. They are stored as ciphertext on-chain, but they can still represent anything: balances, identity data, permissions, or game assets.

A simple record might look like this:

record Balance {
  owner: address,
  amount: u64,
}

Records are tied to the user's address and only readable if you have the view key. That’s a special key that lets users share read-only access to their private data, without giving spending rights.

Storing public state with mappings. Mappings are key-value pairs stored on-chain and visible to anyone. They work like a simple database and are great for keeping data public, such as:

• Voting results

• Public leaderboards

• Token metadata

Example:

mapping votes: address => u8;

You can query this data using Aleo explorer or other blockchain tools.

Example: Mixing private and public state. Aleo lets you move between private and public state in your app. Here’s a simple program where we store the result of a sum in a record:

program sum.aleo {
  record sum {
    public owner: address,
    amount: u64,
  }

  transition main(public a: u64, b: u64) -> sum {
    let c: u64 = a + b;
    return sum {
      owner: self.caller,
      amount: c,
    };
  }
}

Here, a is public, b is private, and the output is stored in a record. Only the owner of that record can view it unless they share their view key.

Async programming for public state. When you update public mappings, you use async functions and Futures. Here’s how that looks:

program counter.aleo {
  mapping total: u8 => u64;

  async transition increment() -> Future {
    return update_count();
  }

  async function update_count() {
    let current: u64 = total.get_or_use(0u8, 0u64);
    let new: u64 = current + 1u64;
    total.set(0u8, new);
  }
}

Async functions are only executed after a proof is verified. Transition functions run first and return a Future. Then the network finalizes the state change.

More info you can find here:

https://developer.aleo.org/concepts/fundamentals/public_private

Calling async transitions from other programs. Let’s say one program calls another:

import counter.aleo;

program dashboard.aleo {
  mapping logs: u8 => scalar;

  async transition update_log(val: u8) -> Future {
    let update_future = counter.aleo/increment();
    return apply_log(val, update_future);
  }

  async function apply_log(val: u8, f: Future) {
    f.await();
    let hash: scalar = BHP256::hash_to_scalar(val);
    logs.set(val, hash);
  }
}

Notice how the Future is passed to an async function and await is used to ensure the call completes.

Private state in async transitions. When working with Aleo's async programming model, it's important to understand a key limitation: you can't create or spend private records directly inside async function blocks. This is because these functions are executed after the transaction has already been proven, which means they can't handle sensitive state updates that require zero-knowledge protection.

However, you can use private records inside transition and async transition functions. These run off-chain, generate the required proof, and are verified by the network before any state is finalized.

So, if you're working with public state, you'll use async function blocks with mappings. But if you're handling private state like encrypted records, stick to transition or async transition functions. Only the record owner can view this data, and only with their view key.

In short:

• Use mappings with async function for public state updates.

• Use records with transition or async transition when dealing with private data.

More info you can find here:

https://docs.leo-lang.org/guides/async

Real-world use case: voting. A great example is voting. You want your individual vote to remain private, but the total result to be public. Aleo’s hybrid model makes this possible.

“In elections, people want to vote, but they don’t want to show other people how they voted. The tally of the votes needs to be public to understand the outcome. Having private votes and public tallies ends up being a capable functionality in applications here.” — Howard Wu

This hybrid approach unlocks use cases that can't be built easily on Ethereum or Zcash.

Final thoughts. Aleo gives you full control over your application’s privacy. Whether you want to store state as encrypted records or readable mappings, you decide what the world can see.

By combining public and private states with zero-knowledge proofs and async execution, Aleo enables a new category of secure and scalable applications.

To know more about Aleo, join now!

• Aleo Twitter

• Aleo Discord

• Aleo Website

• List of Aleo and Leo code and resourses

Prepared by Colliseum