Skip to main content

ZSwap API

@midnight/zswap v3.0.2 • Readme | API

Zswap TypeScript API

This document outlines the usage of the Zswap TS API

Network ID​

Prior to any interaction, setNetworkId should be used to set the NetworkId to target the correct network.

Proof stages​

Most transaction components will be in one of three stages: X, UnprovenX, or ProofErasedX. The UnprovenX stage is always the first one. It is possible to transition to the X stage by proving an UnprovenTransaction through the proof server. For testing, and where proofs aren't necessary, the ProofErasedX stage is used, which can be reached via eraseProof[s] from the other two stages.

Transaction structure​

A Transaction runs in two phases: a guaranteed phase, handling fee payments and fast-to-verify operations, and a fallible phase, handling operations which may fail atomically, separately from the guaranteed phase. It therefore contains:

  • A "guaranteed" Offer
  • Optionally, a "fallible" Offer
  • Contract call information not accessible to this API

It also contains additional cryptographic glue that will be omitted in this document.

Zswap​

A Zswap Offer consists of:

  • A set of Inputs, burning coins.
  • A set of Outputs, creating coins.
  • A set of Transients, indicating a coin that is created and burnt in the same transaction.
  • A mapping from TokenTypes to offer balance, positive when there are more inputs than outputs and vice versa.

Inputs can be created either from a QualifiedCoinInfo and a contract address, if the coin is contract-owned, or from a QualifiedCoinInfo and a ZswapLocalState, if it is user-owned. Similarly, Outputs can be created from a CoinInfo and a contract address for contract-owned coins, or from a CoinInfo and a user's public key(s), if it is user-owned. A Transient is created similarly to a Input, but directly converts an existing Output.

A QualifiedCoinInfo is a CoinInfo with an index into the Merkle tree of coin commitments that can be used to find the relevant coin to spend, while a CoinInfo consists of a coins TokenType, value, and a nonce.

State Structure​

ZswapChainState holds the on-chain state of Zswap, while ZswaplocalState contains the local, wallet state.