zionsdk v0.1.7

Glossary

• l1: the layer 1 block-chain(cortex mainnet)
• zion: the layer-2 network called zion is the zk-rollup of the l1-chain

Usage

we introduce some basic usage of the zion-sdk below,for more details, refer to the example.js for usage and the source code

introduce some usage:

1. Connect to the zion network.
2. Deposit assets from Cortex into zion.
3. Make transfers.
4. Withdraw funds back to Cortex mainnet.

Adding imports

You can import all the content of the zion library with the following statement:

import * as zion from "zion";

normally we only need the Wallet class,

import { Wallet } from "zion";

Connecting to zion network

To interact with zion network users need to know the endpoint of the operator node. (for test, there is a test api server,please set provider based on it for development)

const zionProvider = await zion.getDefaultProvider("dev");

Creating a Wallet

To control your account in zion, use the zion.Wallet object. It can sign transactions with keys stored in zion.Signer and send transaction to zion network using zion.Provider.

zion.Wallet is a wrapper around 2 objects:

• ethers.Signer to sign Cortex transactions.
• zion.Signer to sign native zion transactions.

The private key used by zion.Signer is implicitly derived from Cortex signature of a special message.

// Create Cortex wallet by the metamask
const l1Provider = new ethers.providers.Web3Provider(window.ethereum);
const l1Wallet = l1Provider.getSigner();
// or get by the private-key ...

// Derive zion.Signer from Cortex wallet.
const zionWallet = await zion.Wallet.fromL1Signer(l1Wallet, zionProvider);

// Derive a zion wallet without the signer(there is no need to sign the specical message when first login in, and this wallet could only deposit)
const zionWalletNoKey = await zion.Wallet.fromL1SignerNoKeys(l1Wallet, zionProvider);

Depositing assets from Cortex into zion

We are going to deposit 1.0 CTXC to our zion account.

// we deposit to our self address normally
const deposit = await zionWallet.depositToZionFromL1({
    depositTo: zionWallet.address(),
    token: "CTXC",
    amount: ethers.utils.parseEther("1.0"),
});

After the tx is submitted to the Cortex node, we can track its status using the returned object:

// Await confirmation from the zion operator
// Completes when a promise is issued to process the tx
const depositReceipt = await deposit.awaitReceipt();

// Await verification
// Completes when the tx reaches finality on Cortex
const depositReceipt = await deposit.awaitVerifyReceipt();

Unlocking zion account

To control assets in zion network, an account must register a separate public key once.

// there are 2 situation that the account is locked:
// 1. the account doesn't exist in the zion network
// 2. the account an "empty" account(not initilized)
let is_locked = zionWallet.isSigningKeySet();

let pubkeyUpdate = await zionWallet.setSigningKey({
    feeToken: "CTXC",
});

if (!(await zionWallet.isSigningKeySet())) {
    if ((await zionWallet.getAccountId()) == undefined) {
        throw new Error("Unknown account");
    }

    // As any other kind of transaction, `PubKeyUpdate` transaction requires fee.
    // User doesn't have (but can) to specify the fee amount. If omitted, library will query zion node for fee
    const pubkeyUpdate = await zionWallet.setSigningKey({
        feeToken: "CTXC",
    });

    // Wait until the tx is committed
    await pubkeyUpdate.awaitReceipt();
}

Checking zion account balance

const BalanceInL2 = await zionWallet.getBalance("CTXC");

get the total account state now

const state = await zionWallet.getAccountState();

Making a transfer in zion

const transfer = await zionWallet.zionTransfer({
    toAddress: "${address you want to transfer}",
    token: "CTXC",
    amount: ethers.utils.parseEther("0.999"),
});

To track the status of this transaction:

const transferReceipt = await transfer.awaitReceipt();

Withdrawing funds back to Cortex

const withdraw = await zionWallet.withdrawFromZionToL1({
    toAddress: l1Wallet.address,
    token: "CTXC",
    amount: ethers.utils.parseEther("0.998"),
});

Assets will be withdrawn to the target wallet after the zero-knowledge proof of zion block with this operation is generated and verified by the mainnet contract.

We can wait until ZKP verification is complete:

await withdraw.awaitVerifyReceipt();

// get the histore transaction of the account(from latest to older with limit number)
let txs = await  zionWallet.provider.accountTxs(
    zionWallet.address(),
    {
        from: "latest" | number(e.g. 8),
        limit: 8,
        direction: "newer"|"older"
    }
)

// get the specific data with the tx hash
let txData = await zionWallet.provider.txData(txhash)

// brief tx data
let txStatue = await zionWallet.provider.txStatus(txhash)