numio-zksync-api v0.0.9

NUMIO-ZKSYNC-API

API to communicate with ZKSYNC node. It depends on zksync module to work properly. It was developed to streamline the most common use cases of interaction with zksync node.

1. Create new ethereum wallet and integrate it with zksync node and ethereum blockchain provider (INFURA, local geth)
2. Deposit Ethereum to zksync account. It will check required token fee and make sure that user has enough ETH to make a deposit.
3. Deposit Token to zksync account. It will calculate fee and use correct value to make a deposit. It will make sure that user has neough ETH to make a transaction.
4. Transfer ETH or Tokens between two ZKSYNC accounts. It will calculate correct fee and make sure correct nonce is applied to the transaction.

How to use it in your project

• Install npm module

npm install numio-zksync-api

• Import module in your code

const ZKAPI = require('numio-zksync-api')

How to create a new wallet

In order to create wallet first you have to initialize numio-zksync-api instance. This requires two parameters:

• ZKSYNC node address
• Ethereum provider address. This can be INFURA or local geth node or some other node. For example:

let APIOptions = {
  zkAddress:
    'http://ec2-x-xxx-xxx-xxx.us-east-2.compute.amazonaws.com:3030',
  zkEthProvider:
    'http://ec2-x-xxx-xxx-xxx.us-east-2.compute.amazonaws.com:8545',
}

• Initialize numio-zksync-api

zkSyncApi = new ZKAPI(APIOptions)

Create new random wallet

async createNew(password: string)

This will create new wallet with new random private key.

let result = await zkSyncApi.createNew('testpassword')
zkWallet1 = result.zkWallet

createNew function requires password which will be then used to encrypt ethers wallet keystore. Function returns three parameters:

• keystore - encrypted ethers wallet keystore. this can be saved for later to restore wallet.
• zkWallet - zkWallet instance which can be used to execute all zkSync transactions
• account - ethers wallet instance which can be used to make ETH transfer, check balance and so on.

Create new wallet from mnemonic and path parameter

async createFromMnemonic(mnemonic: string, path: string, password: string)

This will create new wallet instance based on mnemonic and path. Password will be used to encrypt keystore.

var pathA = "m/44'/60'/0'/0/1"
var mnemonic = 'next run impact minimum item plate orchard vehicle dance inform correct dutch'
let result = await zkSyncApi.createFromMnemonic(mnemonic, pathA, 'testpassword')
var zkWalletFromMnemonic = result.zkWallet

This function returns three parameters: keystore, zkWallet, account.Just like createNew function.

Create new wallet from private key

async createFromPrivateKey(privateKey: string)

It will create new wallet instance based on existing privateKey

let privateKey = '12876743239abcdef984234abcdddexxxxxxxxxxxxxxxx'
let result = await zkSyncApi.createFromPrivateKey(privateKey)
var zkWalletFromPK = result.zkWallet

How to make a deposit

The only way to create an account on ZKSYNC node is to deposit some tokens or ETH for specific account. It can be either by depositing from the outside of ZKSYNC or by transfering tokens/ETH from another existing account.

Deposit from the outside of ZKSYNC (from Blockchain Network - L1)

async depositToken(to:string, amount:string,token:string)

• to: address of an account receiving tokens on ZKSYNC node. It is possible to send tokens to itself

• amount: number of tokens to be sent. Amount mu be packable to 5 bytes. To calculate correct amount one can use function

  ZKSYNCAPI.checkAmount(amount: string): string

• token: string describing token to be transfered. ETH is used for Ethereum ETH. Other names can be used: DAI or PHNX or anything registered on ZKSYNC node.

To make a deposit account needs to have enough gas to make a transfer on Ethereum L1 network.

let amount = '100'
let amountChecked = zkSyncApi.checkAmount(amount)
let token = 'ETH'
await zkWallet1.depositToken(zkWallet1.address, amountChecked, token)

How to make a transfer

Users can make transfers within L2 network (ZKSYNC network). The main advantage is that transactions within L2 network are much cheaper and much faster than on normal network. It is possible to execute around 300 transactions per second on ZKSYNC and this number is planned to be increased to few thousands per second.

To make a transfer user needs to have a valid account on ZKSYNC node and have enough tokens to make a transfer and pay a fee. To calculate a fee user can call async zkWallet.getTransferFee(to:string,token:string):

• to: address of an account receiving tokens
• token: token name to be transfered. Fee value will depends on the current price of token to be transfered.

Transfer function

async zkWallet.transfer(to:string,amount:string,token:string,fee:string)

Before transfer can be executed zk Account must be validated by calling function:

async zkWallet.setSigningKey()

<!-- Set sigining key -->
await zkWallet1.setSigningKey()

<!-- Create random account to receive tokens -->
let result = await zkSyncApi.createNew('testpassword')
let tpmZkWallet = result.zkWallet

<!-- Calculate fee -->
let fee = await zkWallet1.getTransferFee(tpmZkWallet.address, 'ETH')

<!-- Calculate packable amount number -->
let amount = '12891274029840'
let checkedAmount = zkSyncApi.checkAmount(amount)

<!-- Make a transfer -->
<!-- Fee must be provided as a string -->
zkWallet1.transfer(tpmZkWallet.address, checkedAmount, 'ETH', fee.toString())