API
Structs
Maybe
Encapsulates an optionally present value. If is_some
is false
, value
should be null(a)
by convention.
export struct Maybe[a] {
is_some: Boolean;
value: a;
}
Either
Disjoint union of a
and b
. Iff is_left
if true
, left
should be
populated, otherwise right
. The other should be null(_)
by convention.
export struct Either[a, b] {
is_left: Boolean;
left: a;
right: b;
}
CurvePoint
A point on the proof systems embedded curve, in affine coordinates.
Only outputs of elliptic curve operations are actually guaranteed to lie on the curve.
export struct CurvePoint {
x: Field;
y: Field;
}
MerkleTreeDigest
The root hash of a Merkle tree, represented by a single Field
.
export struct MerkleTreeDigest { field: Field; }
MerkleTreePathEntry
An entry in a Merkle tree path, indicating if the path leads left or right, and
the root of the sibling node. Primarily used in MerkleTreePath
export struct MerkleTreePathEntry {
sibling: MerkleTreeDigest;
goes_left: Boolean;
}
MerkleTreePath
A path in a depth n
Merkle tree, leading to a leaf of type a
.
Primarily used for merkle_tree_path_root
.
This can be constructed from witness
es that use the compiler output's
find_path_for_leaf
and path_for_leaf
functions.
export struct MerkleTreePath[n, a] {
leaf: a;
path: Vector[n, MerkleTreePathEntry];
}
ContractAddress
The address of a contract, used as a recipient in send
,
send_immediate
,
create_zswap_output
, and mint_token
.
export struct ContractAddress { bytes: Bytes[32]; }
CoinInfo
The description of a newly created coin, used in outputting coins, or spending/receiving coins that originate in the current transaction.
nonce
can be deterministically derived with evolve_nonce
.
Used in:
export struct CoinInfo {
nonce: Bytes[32];
color: Bytes[32];
value: Unsigned Integer[64];
}
QualifiedCoinInfo
The description of an existing coin in the ledger, ready to be spent.
Used in:
export struct QualifiedCoinInfo {
nonce: Bytes[32];
color: Bytes[32];
value: Unsigned Integer[64];
mt_index: Unsigned Integer[64];
}
ZswapCoinPublicKey
The public key used to output a CoinInfo
to a user, used as a
recipient in send
, send_immediate
, and
create_zswap_output
.
export struct ZswapCoinPublicKey { bytes: Bytes[32]; }
SendResult
The output of send
and send_immediate
,
detailing the created coin, and the change from spending the input, if
applicable.
export struct SendResult {
change: Maybe[CoinInfo];
sent: CoinInfo;
}
Circuits
some
Constructs a Maybe[a]
containing an element of type a
export circuit some[a](value: a): Maybe[a];
none
Constructs a Maybe[a]
containing nothing
export circuit none[a](): Maybe[a];
left
Construct an Either[a, b]
containing the a
item of the disjoint
union
export circuit left[a, b](value: a): Either[a, b];
right
Constructs an Either[a, b]
containing the b
item of the disjoint
union
export circuit right[a, b](value: b): Either[a, b];
transient_hash
Builtin transient hash compression function
This function is a circuit-efficient compression function from field elements to field elements, which is not guaranteed to persist between upgrades. It should not be used to derive state data, but can be used for consistency checks.
export circuit transient_hash(x: Field, y: Field): Field;
transient_commit
Builtin transient commitment function
This function is a circuit-efficient commitment function over arbitrary types, and a field element commitment opening, to field elements, which is not guaranteed to persist between upgrades. It should not be used to derive state data, but can be used for consistency checks.
export circuit transient_commit[a](value: a, rand: Field): Field;
persistent_hash
Builtin persistent hash compression function
This function is a non-circuit-optimised compression function from two 256-bit
bytestrings to one 256-bit bytestring. It is guaranteed to persist between
upgrades, with the exception of devnet, where this function is provided, but
mocked using transient_hash
. It should be used to derive
state data, and not for consistency checks where avoidable.
export circuit persistent_hash(x: Bytes[32], y: Bytes[32]): Bytes[32];
persistent_commit
Builtin persistent commitment function
This function is a non-circuit-optimised commitment function from arbitrary
values representable in Compact, and a 256-bit bytestring opening, to a 256-bit
bytestring. It is guaranteed to persist between upgrades, with the exception of
devnet, where this function is provided, but mocked using
transient_commit
. It should be used to derive state
data, and not for consistency checks where avoidable.
export circuit persistent_commit[a](value: a, rand: Bytes[32]): Bytes[32];
degrade_to_transient
This function "degrades" the output of a persistent_hash
or persistent_commit
to a field element, which can then
be used in transient_hash
or
transient_commit
.
export circuit degrade_to_transient(x: Bytes[32]) : Field;
ec_add
This function add two elliptic CurvePoint
s (in multiplicative
notation)
export circuit ec_add(a: CurvePoint, b: CurvePoint): CurvePoint;
ec_mul
This function multiplies an elliptic CurvePoint
by a scalar
(in multiplicative notation)
export circuit ec_mul(a: CurvePoint, b: Field): CurvePoint;
ec_mul_generator
This function multiplies the primary group generator of the embedded curve by a scalar (in multiplicative notation)
export circuit ec_mul_generator(b: Field): CurvePoint;
hash_to_curve
This function maps arbitrary types to CurvePoint
s.
Outputs are guaranteed to have unknown discrete logarithm with respect to the group base, and any other output, but are not guaranteed to be unique (a given input can be proven correct for multiple outputs).
Inputs of different types a
may have the same output, if they have the same
field-aligned binary representation.
export circuit hash_to_curve[a](value: a): CurvePoint;
merkle_tree_path_root
Derives the Merkle tree root of a MerkleTreePath
, which
should match the root of the tree that this path originated from.
export circuit merkle_tree_path_root[n, a](path: MerkleTreePath[n, a]): MerkleTreeDigest;
native_token
Returns the token type of the native token
export circuit native_token(): Bytes[32];
token_type
Transforms a domain seperator for the given contract into a globally namespaced
token type. A contract can issue tokens for its domain seperators, which lets
it create new tokens, but due to collision resistance, it cannot mint tokens
for another contract's token type. This is used as the color
field in CoinInfo
.
export circuit token_type(domain_sep: Bytes[32], contract: ContractAddress): Bytes[32];
mint_token
Creates a new coin, minted by this contract, and sends it to the given
recipient. Returns the corresponding CoinInfo
. This requires
inputting a unique nonce to function securely, it is left to the user how to
produce this.
export circuit mint_token(
domain_sep: Bytes[32],
value: Unsigned Integer[64],
nonce: Bytes[32],
recipient: Either[ZswapCoinPublicKey, ContractAddress]
): CoinInfo;
evolve_nonce
Deterministically derives a CoinInfo
nonce from a counter index,
and a prior nonce.
export circuit evolve_nonce(
index: Unsigned Integer[64],
nonce: Bytes[32]
): Bytes[32];
burn_address
Returns a payment address that guarantees any coins sent to it are burned.
export circuit burn_address(): Either[ZswapCoinPublicKey, ContractAddress];
receive
Receives a coin, adding a validation condition requiring this coin to be present as an output addressed to this contract, and not received by another call
export circuit receive(coin: CoinInfo): Void;
send
Sends given value from a coin owned by the contract to a recipient. Any change is returned and should be managed by the contract.
Note that this does not currently create coin ciphertexts, so sending to a user public key except for the current user will not lead to this user being informed of the coin they've been sent.
export circuit send(input: QualifiedCoinInfo, recipient: Either[ZswapCoinPublicKey, ContractAddress], value: Unsigned Integer[64]): SendResult;
send_immediate
Like send
, but for coins created within this transaction
export circuit send_immediate(input: CoinInfo, target: Either[ZswapCoinPublicKey, ContractAddress], value: Unsigned Integer[64]): SendResult;
merge_coin
Takes two coins stored on the ledger, and combines them into one
export circuit merge_coin(a: QualifiedCoinInfo, b: QualifiedCoinInfo): CoinInfo;
merge_coin_immediate
Takes one coin stored on the ledger, and one created within this transaction, and combines them into one
export circuit merge_coin_immediate(a: QualifiedCoinInfo, b: CoinInfo): CoinInfo;
Witnesses
own_public_key
Returns the ZswapCoinPublicKey
of the end-user
creating this transaction.
export witness own_public_key(): ZswapCoinPublicKey;
create_zswap_input
Notifies the context to create a new Zswap input originating from this call.
Should typically not be called manually, prefer send
and
send_immediate
instead.
export witness create_zswap_input(coin: QualifiedCoinInfo): Void;
create_zswap_output
Notifies the context to create a new Zswap output originating from this call.
Should typically not be called manually, prefer send
and
send_immediate
, and receive
instead.
export witness create_zswap_output(coin: CoinInfo, recipient: Either[ZswapCoinPublicKey, ContractAddress]): Void;