Circuit Types

Circuit Data Types

There are two types of values inside a circuit: CircuitValue and CircuitValue256. Due to some specifics of our ZK proving system, a CircuitValue can be at most 253 bits. Since EVM slots are 256 bits, we've created a CircuitValue256 that represents values in hi-lo form (hi is the most significant 128 bits, lo is the 128 least significant bits).

Here are the methods available on a CircuitValue object:

class CircuitValue {
    // returns the value as a bigint
    value(): bigint;
    
    // returns the value as a number
    number(): number;
    
    // returns the value as an address string
    address(): string;
    
    // converts the CircuitValue to a CircuitValue256 inside the circuit
    toCircuitValue256(): CircuitValue256;
}

Here are the methods available on a CircuitValue256 object.

class CircuitValue256 {
    // returns the value as a bigint
    value(): bigint;
    
    // returns the value as a hex string
    hex(): string;
    
    // returns the `hi` CircuitValue
    hi(): CircuitValue
    
    // returns the `lo` CircuitValue
    lo(): CircuitValue
    
    // constrains that the CircuitValue256 can fit in 253 bits
    // and constrains out = 2**128 * hi + lo
    toCircuitValue(): CircuitValue
}

By default all data results return CircuitValue256. To use these results in other circuit operations that take CircuitValues, you must call .toCircuitValue(). If you know that the data you are querying is less than 253 bits (ie. block number, address, uint128, etc.), this is totally safe. For values which may overflow 253 bits (such as storage slots, bytes32), this will fail if the value actually overflows (in particular, if the hi CircuitValue exceeds 125 bits).