Program Types - SnarkVM

The program module provides data structures for Aleo programs and their execution. These types represent program state, function parameters, and return values.

Identifier

A named identifier for program components (variables, functions, structs, etc.).

Structure

pub struct Identifier<N: Network> {
    // Internal identifier representation
}

Rules

Must be lowercase alphanumeric with underscores
Cannot be a reserved keyword
Maximum length depends on context

Example

use snarkvm_console::program::Identifier;
use snarkvm_console::network::MainnetV0;
use std::str::FromStr;

type CurrentNetwork = MainnetV0;

let id = Identifier::<CurrentNetwork>::from_str("my_variable")?;
let func = Identifier::<CurrentNetwork>::from_str("transfer_public")?;

ProgramID

A unique identifier for an Aleo program.

Structure

pub struct ProgramID<N: Network> {
    name: Identifier<N>,
    network: Identifier<N>,
}

name

Identifier<N>

The program name (lowercase alphanumeric)

network

Identifier<N>

The network-level domain (NLD), must be “aleo”

Methods

name

fn name(&self) -> &Identifier<N>

Returns the program name

network

fn network(&self) -> &Identifier<N>

Returns the network-level domain

is_aleo

fn is_aleo(&self) -> bool

Returns true if the network-level domain is “aleo”

Format

Program IDs follow the format {name}.{network}:

let program_id = ProgramID::<CurrentNetwork>::from_str("credits.aleo")?;
let program_id = ProgramID::<CurrentNetwork>::from_str("token.aleo")?;
let program_id = ProgramID::<CurrentNetwork>::from_str("my_program.aleo")?;

assert!(program_id.is_aleo());

Literal

A primitive value in Aleo programs.

Variants

pub enum Literal<N: Network> {
    Address(Address<N>),
    Boolean(Boolean<N>),
    Field(Field<N>),
    Group(Group<N>),
    I8(I8<N>),
    I16(I16<N>),
    I32(I32<N>),
    I64(I64<N>),
    I128(I128<N>),
    U8(U8<N>),
    U16(U16<N>),
    U32(U32<N>),
    U64(U64<N>),
    U128(U128<N>),
    Scalar(Scalar<N>),
    Signature(Box<Signature<N>>),
    String(StringType<N>),
}

Type Checking

Literals have an associated LiteralType:

pub enum LiteralType {
    Address,
    Boolean,
    Field,
    Group,
    I8, I16, I32, I64, I128,
    U8, U16, U32, U64, U128,
    Scalar,
    Signature,
    String,
}

Example

use snarkvm_console::program::Literal;
use snarkvm_console::types::{Field, Boolean, U64};
use snarkvm_console::network::MainnetV0;

type CurrentNetwork = MainnetV0;

let lit_bool = Literal::Boolean(Boolean::new(true));
let lit_field = Literal::Field(Field::from_u64(42));
let lit_u64 = Literal::U64(U64::new(1000));

// Parse from string
let lit = Literal::<CurrentNetwork>::from_str("123field")?;
let lit = Literal::<CurrentNetwork>::from_str("true")?;
let lit = Literal::<CurrentNetwork>::from_str("42u64")?;

Casting

Literals support type casting:

use snarkvm_console::program::Cast;

let field_lit = Literal::Field(Field::from_u64(42));
let u64_lit = field_lit.cast(LiteralType::U64)?;

Plaintext

A plaintext value that can be a literal, struct, or array.

Variants

pub enum Plaintext<N: Network> {
    Literal(Literal<N>, OnceLock<Vec<bool>>),
    Struct(IndexMap<Identifier<N>, Plaintext<N>>, OnceLock<Vec<bool>>),
    Array(Vec<Plaintext<N>>, OnceLock<Vec<bool>>),
}

Literal

(Literal<N>, OnceLock<Vec<bool>>)

A primitive value with cached bit representation

Struct

(IndexMap<Identifier<N>, Plaintext<N>>, OnceLock<Vec<bool>>)

A struct with named fields and cached bit representation

Array

(Vec<Plaintext<N>>, OnceLock<Vec<bool>>)

An array of plaintext values with cached bit representation

Methods

from_bit_array

fn from_bit_array(bits: Vec<bool>, length: u32) -> Result<Self>

Creates a plaintext from a bit array

as_bit_array

fn as_bit_array(&self) -> Result<Vec<bool>>

Returns the plaintext as a bit array

as_byte_array

fn as_byte_array(&self) -> Result<Vec<u8>>

Returns the plaintext as a byte array

as_field_array

fn as_field_array(&self) -> Result<Vec<Field<N>>>

Returns the plaintext as a field array

Example - Literals

use snarkvm_console::program::{Plaintext, Literal};
use snarkvm_console::types::{Field, Boolean};
use snarkvm_console::network::MainnetV0;

type CurrentNetwork = MainnetV0;

// From literal
let plaintext = Plaintext::from(Literal::Boolean(Boolean::new(true)));
let plaintext = Plaintext::from(Literal::Field(Field::from_u64(42)));

// Parse from string
let plaintext = Plaintext::<CurrentNetwork>::from_str("true")?;
let plaintext = Plaintext::<CurrentNetwork>::from_str("123field")?;

Example - Structs

use snarkvm_console::program::{Plaintext, Identifier};
use indexmap::IndexMap;

// Create a struct
let mut members = IndexMap::new();
members.insert(
    Identifier::from_str("x")?,
    Plaintext::from_str("1field")?
);
members.insert(
    Identifier::from_str("y")?,
    Plaintext::from_str("2field")?
);
let plaintext = Plaintext::Struct(members, OnceLock::new());

// Parse from string
let plaintext = Plaintext::<CurrentNetwork>::from_str(
    "{ x: 1field, y: 2field }"
)?;

Example - Arrays

// Create an array
let elements = vec![
    Plaintext::from_str("1field")?,
    Plaintext::from_str("2field")?,
    Plaintext::from_str("3field")?,
];
let plaintext = Plaintext::Array(elements, OnceLock::new());

// Parse from string
let plaintext = Plaintext::<CurrentNetwork>::from_str(
    "[1field, 2field, 3field]"
)?;

// U8 array
let bytes = vec![U8::new(1), U8::new(2), U8::new(3)];
let plaintext = Plaintext::from(bytes);

Nested Structures

Plaintext supports arbitrary nesting:

let plaintext = Plaintext::<CurrentNetwork>::from_str(
    "{
        name: \"Alice\",
        balance: 1000u64,
        metadata: {
            created: 1234567890u64,
            tags: [1u8, 2u8, 3u8]
        }
    }"
)?;

Record

A record is an encrypted state object with an owner.

Structure

pub struct Record<N: Network, Private: Visibility> {
    owner: Owner<N, Private>,
    data: IndexMap<Identifier<N>, Entry<N, Private>>,
    nonce: Group<N>,
    version: U8<N>,
}

owner

Owner<N, Private>

The owner of the record (address or ciphertext)

data

IndexMap<Identifier<N>, Entry<N, Private>>

The record data (named entries)

nonce

Group<N>

The nonce used for encryption and commitment

version

U8<N>

Version 0 uses BHP hash, version 1 uses BHP commitment

Owner

pub enum Owner<N: Network, Private: Visibility> {
    Public(Address<N>),
    Private(Private),
}

Entry

Record entries can be public or private:

pub enum Entry<N: Network, Private: Visibility> {
    Constant(Plaintext<N>),
    Public(Plaintext<N>),
    Private(Private),
}

Methods

from_plaintext

fn from_plaintext(...) -> Result<Record<N, Plaintext<N>>>

Creates a plaintext record

from_ciphertext

fn from_ciphertext(...) -> Result<Record<N, Ciphertext<N>>>

Creates a ciphertext record

owner

fn owner(&self) -> &Owner<N, Private>

Returns the record owner

data

fn data(&self) -> &IndexMap<Identifier<N>, Entry<N, Private>>

Returns the record data

nonce

fn nonce(&self) -> &Group<N>

Returns the nonce

version

fn version(&self) -> &U8<N>

Returns the version

is_hiding

fn is_hiding(&self) -> bool

Returns true if using hiding commitments (version != 0)

encrypt

fn encrypt(&self, randomizer: Scalar<N>) -> Result<Record<N, Ciphertext<N>>>

Encrypts the record

decrypt

fn decrypt(view_key: &ViewKey<N>) -> Result<Record<N, Plaintext<N>>>

Decrypts a ciphertext record

Example

use snarkvm_console::program::{Record, Owner, Entry, Identifier};
use snarkvm_console::account::Address;
use snarkvm_console::types::{Group, U8};
use snarkvm_console::network::MainnetV0;
use indexmap::IndexMap;

type CurrentNetwork = MainnetV0;

// Create record data
let mut data = IndexMap::new();
data.insert(
    Identifier::from_str("balance")?,
    Entry::Private(Plaintext::from_str("1000u64")?)
);
data.insert(
    Identifier::from_str("token_id")?,
    Entry::Public(Plaintext::from_str("1u64")?)
);

// Create the record
let owner = Owner::Private(address);
let nonce = Group::generator();
let version = U8::new(1); // Use hiding commitments
let record = Record::from_plaintext(owner, data, nonce, version)?;

// Encrypt
let ciphertext_record = record.encrypt(randomizer)?;

// Decrypt
let plaintext_record = ciphertext_record.decrypt(&view_key)?;

Value

A value can be a plaintext, record, or future.

Variants

pub enum Value<N: Network> {
    Plaintext(Plaintext<N>),
    Record(Record<N, Plaintext<N>>),
    Future(Future<N>),
}

Plaintext

Plaintext<N>

A plaintext value (literal, struct, or array)

Record

Record<N, Plaintext<N>>

A record value with owner and data

Future

Future<N>

A future representing deferred computation

Conversions

Value implements From for all its variants:

let value = Value::from(literal);
let value = Value::from(plaintext);
let value = Value::from(record);
let value = Value::from(future);

Example

use snarkvm_console::program::{Value, Plaintext, Literal};
use snarkvm_console::types::Field;
use snarkvm_console::network::MainnetV0;

type CurrentNetwork = MainnetV0;

// From literal
let lit = Literal::Field(Field::from_u64(42));
let value = Value::from(lit);

// From plaintext
let plaintext = Plaintext::from_str("{ x: 1field, y: 2field }")?;
let value = Value::from(plaintext);

// From record
let value = Value::from(record);

// Pattern matching
match value {
    Value::Plaintext(p) => println!("Plaintext: {}", p),
    Value::Record(r) => println!("Record with {} entries", r.data().len()),
    Value::Future(f) => println!("Future"),
}

Request and Response

Types for function calls.

Request

Represents a signed function request:

pub struct Request<N: Network> {
    // Internal request structure
}

sign

fn sign(...) -> Result<Self>

Signs a request with a private key

verify

fn verify(&self, ...) -> bool

Verifies the request signature

Response

Represents function outputs:

pub struct Response<N: Network> {
    // Internal response structure
}

Access Paths

Access nested data in structs and arrays:

pub enum Access<N: Network> {
    Member(Identifier<N>),
    Index(U32<N>),
}

Example

use snarkvm_console::program::Access;

// Access struct member
let access = Access::Member(Identifier::from_str("balance")?);

// Access array index
let access = Access::Index(U32::new(0));

Type System

Types are checked at compile time:

pub enum PlaintextType<N: Network> {
    Literal(LiteralType),
    Struct(Identifier<N>),
    Array(Box<PlaintextType<N>>, U32<N>),
}

pub enum ValueType<N: Network> {
    Constant(PlaintextType<N>),
    Public(PlaintextType<N>),
    Private(PlaintextType<N>),
    Record(Identifier<N>),
    Future(Locator<N>),
}

Overview

Algorithms

Console

Circuit

Synthesizer

Ledger

Utilities

Documentation Index

​Identifier

​Structure

​Rules

​Example

​ProgramID

​Structure

​Methods

​Format

​Literal

​Variants

​Type Checking

​Example

​Casting

​Plaintext

​Variants

​Methods

​Example - Literals

​Example - Structs

​Example - Arrays

​Nested Structures

​Record

​Structure

​Owner

​Entry

​Methods

​Example

​Value

​Variants

​Conversions

​Example

​Request and Response

​Request

​Response

​Access Paths

​Example

​Type System

​See Also

Build docs developers (and LLMs) love

Identifier

Structure

Rules

Example

ProgramID

Structure

Methods

Format

Literal

Variants

Type Checking

Example

Casting

Plaintext

Variants

Methods

Example - Literals

Example - Structs

Example - Arrays

Nested Structures

Record

Structure

Owner

Entry

Methods

Example

Value

Variants

Conversions

Example

Request and Response

Request

Response

Access Paths

Example

Type System

See Also