EList

The Inco Lightning SDK provides encrypted lists (EList) — confidential, immutable, homogeneous dynamic arrays of Euint128 or Ebool values. Like the scalar operations, every elist operation is a cross-program invocation that returns a new handle; the covalidator network performs the actual list computation off-chain. The EList, EListType types are documented in Types. Element values are passed as raw u128 handles (Euint128.0 / Ebool.0), and encrypted indices are Euint128.

Each elist handle is IMMUTABLE, so a handle will forever point to a particular list of values. Any operation on a list will return a new handle pointing to a new list, leaving the original list unchanged.

Constructor Operations

Function	Description	Signature
`new_elist_from_handles`	Create a list from existing handles	`(CpiContext, Vec<u128>, u8) -> Result<EList>`
`new_elist_from_inputs`	Create a list from client-encrypted inputs	`(CpiContext, Vec<Vec<u8>>, u8, Pubkey) -> Result<EList>`
`list_range`	Create an ordered list of `[start, end)`	`(CpiContext, u16, u16, u8) -> Result<EList>`

Read Operations

Function	Description	Signature
`list_get`	Get the element at a plaintext index	`(CpiContext, EList, u16) -> Result<u128>`
`list_get_or`	Get the element at an encrypted index, or a default	`(CpiContext, EList, Euint128, u128) -> Result<u128>`

Modifying Operations

Operations that produce a new list return a new EList handle.

Function	Description	Signature
`list_append`	Append an element to the end	`(CpiContext, EList, u128) -> Result<EList>`
`list_insert`	Insert an element at an encrypted index	`(CpiContext, EList, Euint128, u128) -> Result<EList>`
`list_set`	Replace the element at an encrypted index	`(CpiContext, EList, Euint128, u128) -> Result<EList>`
`list_concat`	Concatenate two lists	`(CpiContext, EList, EList) -> Result<EList>`
`list_slice`	Slice from an encrypted start for `len`	`(CpiContext, EList, Euint128, u16, u128) -> Result<EList>`
`list_shuffle`	Shuffle elements	`(CpiContext, EList, u64) -> Result<EList>`
`list_reverse`	Reverse elements	`(CpiContext, EList) -> Result<EList>`

Every operation that produces a new handle requires calling allow() to grant decryption access. Use the remaining_accounts pattern to pass allowance PDAs and grant access in the same transaction. See Access Control for simulation patterns on the client side.

Creating new EList from existing handles

new_elist_from_handles(handles, list_type) creates a new list from an existing list of handles and returns a new elist handle. Type must be specified ahead of time and can not be changed. Handles type must match the type of the list container.

use inco_lightning::cpi::accounts::Operation;
use inco_lightning::cpi::{new_elist_from_handles, as_euint128};
use inco_lightning::types::{EList, EListType, Euint128};

let mut handles: Vec<u128> = Vec::new();
for i in 1..=5u128 {
    let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
    let handle: Euint128 = as_euint128(cpi_ctx, i)?;
    handles.push(handle.0);
}

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let my_list: EList = new_elist_from_handles(cpi_ctx, handles, EListType::Euint128 as u8)?;
// my_list = E([1, 2, 3, 4, 5])

Creating new EList from user inputs

Sometimes it’s desired to create an elist from user inputs directly, like from a javascript dApp. new_elist_from_inputs(inputs, list_type, user) takes an array of user-encrypted ciphertexts and returns a new elist handle. Expected type must be specified ahead of time and can not be changed.

use inco_lightning::cpi::{new_elist_from_inputs};

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let list: EList = new_elist_from_inputs(cpi_ctx, inputs, EListType::Euint128 as u8, user)?;

Length and ListType

The length and element type of a list travel inside the EList handle itself and are read directly from the struct fields — no CPI is required.

let len: u16 = my_list.length;       // == 5
let list_type: u8 = my_list.list_type; // EListType::Euint128 as u8

Note: It is IMPORTANT to keep in mind that the length of the elist is ALWAYS PUBLIC and encoded inside the handle itself. It’s an intentional design choice to make program behavior more predictable at a cost of leaking the length of the list, because it can (for the most part) always be predicted by looking at history of on-chain operations.

Append

list_append(list, value) appends a Euint128 or Ebool element at the end of a list, returning a new modified list handle.

use inco_lightning::cpi::{list_append, as_euint128};

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let value: Euint128 = as_euint128(cpi_ctx, 5)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let my_list: EList = list_append(cpi_ctx, my_list, value.0)?;
// [].append(5) == [5]

Insert

list_insert(list, index, value) inserts a hidden element at an encrypted position, returning a new modified list.

Note however that if the index is out of range, it works similarly to list_append() and appends the element at the end of the list.

use inco_lightning::cpi::{list_insert, as_euint128};

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let index: Euint128 = as_euint128(cpi_ctx, 0)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let value: Euint128 = as_euint128(cpi_ctx, 5)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let inserted_list: EList = list_insert(cpi_ctx, my_list, index, value.0)?;
// [10].insert(0, 5) == [5, 10]

Get

list_get(list, index) returns the hidden element at a plaintext position as a raw u128 handle.

If the plaintext index is out of range, the operation reverts with IndexOutOfRange.

use inco_lightning::cpi::list_get;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let handle: u128 = list_get(cpi_ctx, my_list, 0)?;
let element = Euint128(handle);

GetOr

list_get_or(list, index, default_value) returns the hidden element at an encrypted position. Returns a handle to the hidden element if the index is within range, otherwise returns the default value.

use inco_lightning::cpi::{list_get_or, as_euint128};

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let index: Euint128 = as_euint128(cpi_ctx, 1)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let default_value: Euint128 = as_euint128(cpi_ctx, 0)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let handle: u128 = list_get_or(cpi_ctx, my_list, index, default_value.0)?;
// [5, 10].getOr(1, 0) == 10

Set

list_set(list, index, value) replaces an element at an encrypted index and returns a new modified list.

Note: If the encrypted index is out of range, the operation is ignored and the same list is returned (although with a new handle, in order to not leak information).

use inco_lightning::cpi::{list_set, as_euint128};

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let index: Euint128 = as_euint128(cpi_ctx, 1)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let new_value: Euint128 = as_euint128(cpi_ctx, 2)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let my_list: EList = list_set(cpi_ctx, my_list, index, new_value.0)?;
// [5, 10].set(1, 2) == [5, 2]

Concat

list_concat(lhs, rhs) concatenates two elists into one and returns a new concatenated elist. The length of the new list will be length(lhs) + length(rhs).

Both lists must have the same element type, otherwise it reverts with ListTypeMismatch.

use inco_lightning::cpi::list_concat;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let joint_list: EList = list_concat(cpi_ctx, list_a, list_b)?;
// [5, 10].concat([5, 10]) == [5, 10, 5, 10]

Slice

list_slice(list, start, len, default_value) slices at a hidden start position for a specified length, returning a new sliced list of the specified length.

Note that if the encrypted start position is out of bounds, the resulting list will be filled with the provided default value.

use inco_lightning::cpi::{list_slice, as_euint128};

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let start: Euint128 = as_euint128(cpi_ctx, 1)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let default_value: Euint128 = as_euint128(cpi_ctx, 0)?;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let sliced_list: EList = list_slice(cpi_ctx, my_list, start, 2, default_value.0)?;
// [5, 10, 15].sliceLen(1, 2, 0) == [10, 15]

Range

list_range(start, end, list_type) creates a new list (or a “set”) and populates it with ordered values from within the range. The length of the new list will be equal to end - start.

use inco_lightning::cpi::list_range;
use inco_lightning::types::EListType;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let my_list: EList = list_range(cpi_ctx, 0, 5, EListType::Euint128 as u8)?;
// my_list = E([0, 1, 2, 3, 4])

start must be less than or equal to end, otherwise it reverts with InvalidRange. The range values [start, end) must fit within the bit width of the list_type.

Reverse

list_reverse(list) reverses elements in a list — the first element becomes last, and so on.

use inco_lightning::cpi::list_reverse;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let reversed_list: EList = list_reverse(cpi_ctx, my_list)?;
// [5, 10].reverse() == [10, 5]

Shuffle

list_shuffle(list, counter) deterministically shuffles elements within a list, returning a new shuffled list with the same length. The caller-supplied counter is mixed into the operation as a nonce.

use inco_lightning::cpi::list_shuffle;

let cpi_ctx = CpiContext::new(inco.clone(), Operation { signer: signer.clone() });
let shuffled_list: EList = list_shuffle(cpi_ctx, my_list, counter)?;
// [5, 10].shuffle() could return [10, 5] or [5, 10]

Handles are deterministically derived from operations, so the same operation on the same list with the same inputs always produces the same handle.

Overview

Build a dApp

Reference

Tutorials

EList

EList

Constructor Operations

Read Operations

Modifying Operations

Creating new EList from existing handles

Creating new EList from user inputs

Length and ListType

Append

Insert

Get

GetOr

Set

Concat

Slice

Range

Reverse

Shuffle

​EList

​Constructor Operations

​Read Operations

​Modifying Operations

​Creating new EList from existing handles

​Creating new EList from user inputs

​Length and ListType

​Append

​Insert

​Get

​GetOr

​Set

​Concat

​Slice

​Range

​Reverse

​Shuffle

EList

Constructor Operations

Read Operations

Modifying Operations

Creating new EList from existing handles

Creating new EList from user inputs

Length and ListType

Append

Insert

Get

GetOr

Set

Concat

Slice

Range

Reverse

Shuffle