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:
- Connect to the zion network.
- Deposit assets from Cortex into zion.
- Make transfers.
- 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)