namillum
Version:
Bubble Protocol SDK
279 lines (213 loc) • 8.58 kB
Markdown
---
sidebar_position: 1
tags:
- zilliqa-js
- interaction
- state
- deploy
- event
- listener
- query
- transaction
- batch
- sign
---
# zilliqa-js quickstart
## Getting started
You will need Node and NPM installed on your machine for this guide.
Read the [repo readme](https://github.com/Zilliqa/Zilliqa-JavaScript-Library) to get started with `npm installing` zilliqa-js to your local repo.
Create a burner testing wallet and fund it with tokens from the [faucet](https://dev-wallet.zilliqa.com/faucet?network=testnet).
:::danger
Do not publish your private key as a git artefact, the wallet is at risk.
:::
:::tip
Use a .env file and add it to your .gitignore
:::
## HelloWorld Interaction Example
Review the documentation from the [examples repo for zilliqa-js](https://github.com/Zilliqa/Zilliqa-JavaScript-Library-Examples)
Call a specific example by installing the dependencies and invoking the example command.
In this example we are calling the transition `setHello` with on the `HelloWorld` contract with one vname called `msg` which has the value `newMsg` the contract is at address `zil1v6tjt9s0nua80tvvays5m2g763npxgkez0gnnq` on the `dev-api testnet`.
```ocaml
transition setHello (msg : String)
```
```bash
git clone Zilliqa/Zilliqa-JavaScript-Library-Examples .
cd Zilliqa-JavaScript-Library-Examples
cd node
npm i
node helloWorld.js
```
```js
// Import zilliqa-js
const { BN, Long, bytes, units } = require("@zilliqa-js/util");
const { Zilliqa } = require("@zilliqa-js/zilliqa");
const {
toBech32Address,
getAddressFromPrivateKey,
} = require("@zilliqa-js/crypto");
// What network to connect on
const zilliqa = new Zilliqa("https://dev-api.zilliqa.com");
// These are set by the core protocol, and may vary per-chain and network.
// For more information: https://apidocs.zilliqa.com/?shell#getnetworkid
const chainId = 333; // chainId of the developer testnet
const msgVersion = 1; // current msgVersion
const VERSION = bytes.pack(chainId, msgVersion);
// Populate the wallet with an account
const privateKey =
"deb5c896228f8515146aa16f94a558ba14e52d8496b4b267b2d59cd9036f39a6";
zilliqa.wallet.addByPrivateKey(privateKey);
const address = getAddressFromPrivateKey(privateKey);
console.log(`My account address is: ${address}`);
console.log(`My account bech32 address is: ${toBech32Address(address)}`);
async function testBlockchain() {
try {
// Get Balance
const balance = await zilliqa.blockchain.getBalance(address);
// Get Minimum Gas Price from blockchain
const minGasPrice = await zilliqa.blockchain.getMinimumGasPrice();
console.log(`Your account balance is:`);
console.log(balance.result);
console.log(`Current Minimum Gas Price: ${minGasPrice.result}`);
const myGasPrice = units.toQa("2000", units.Units.Li); // Gas Price that will be used by all transactions
console.log(`My Gas Price ${myGasPrice.toString()}`);
const isGasSufficient = myGasPrice.gte(new BN(minGasPrice.result)); // Checks if your gas price is less than the minimum gas price
console.log(`Is the gas price sufficient? ${isGasSufficient}`);
const deployedContract = zilliqa.contracts.at(
"zil1v6tjt9s0nua80tvvays5m2g763npxgkez0gnnq"
);
// Create a new timebased message and call setHello
// Also notice here we have a default function parameter named toDs as mentioned above.
// For calling a smart contract, any transaction can be processed in the DS but not every transaction can be processed in the shards.
// For those transactions are involved in chain call, the value of toDs should always be true.
// If a transaction of contract invocation is sent to a shard and if the shard is not allowed to process it, then the transaction will be dropped.
const newMsg = "Hello, the time is " + Date.now();
console.log("Calling setHello transition with msg: " + newMsg);
const callTx = await deployedContract.callWithoutConfirm(
"setHello",
[
{
vname: "msg",
type: "String",
value: newMsg,
},
],
{
// amount, gasPrice and gasLimit must be explicitly provided
version: VERSION,
amount: new BN(0),
gasPrice: myGasPrice,
gasLimit: Long.fromNumber(8000),
},
false
);
console.log(callTx.bytes);
// process confirm
console.log(`The transaction id is:`, callTx.id);
console.log(`Waiting transaction be confirmed`);
const confirmedTxn = await callTx.confirm(callTx.id);
console.log(`The transaction status is:`);
console.log(confirmedTxn.receipt);
if (confirmedTxn.receipt.success === true) {
console.log(`Contract address is: ${deployedContract.address}`);
}
} catch (err) {
console.log(err);
}
}
testBlockchain();
```
To which, the console will respond with.
```bash
My account address is: 0x8254b2C9aCdf181d5d6796d63320fBb20D4Edd12
My account bech32 address is: zil1sf2t9jdvmuvp6ht8jmtrxg8mkgx5ahgj6h833r
Your account balance is:
{ balance: '10722145999990000', nonce: 1468 }
Current Minimum Gas Price: 2000000000
My Gas Price 2000000000
Is the gas price sufficient? true
Sending a payment transaction to the network...
The transaction id is: 035a2ae08d0b4d12f31ee6c0315d91b4bb9150c1f078fc88e0ee3b5640f2d318
The transaction status is:
{ cumulative_gas: 50, epoch_num: '3129050', success: true }
Deploying a new contract....
Deployment Transaction ID: 6a67c5d1fb65f7fae9c02ee81b37fb5855bbfd3d17d163a908bb5f667419d1df
Deployment Transaction Receipt:
{ cumulative_gas: 482, epoch_num: '3129052', success: true }
The contract address is:
0xD1F5c962F1c6A77253BFD799B3472D05de414ae2
Calling setHello transition with msg: Hello, the time is 1629086853792
{
"accepted": false,
"cumulative_gas": 357,
"epoch_num": "3129054",
"event_logs": [
{
"_eventname": "setHello()",
"address": "0xd1f5c962f1c6a77253bfd799b3472d05de414ae2",
"params": [
{
"type": "Int32",
"value": "2",
"vname": "code"
}
]
}
],
"success": true
}
Getting contract state...
The state of the contract is:
{
"_balance": "0",
"welcome_msg": "Hello, the time is 1629086853792"
}
```
## Address Interaction
```js
const { toBech32Address, toChecksumAddress } = require("@zilliqa-js/crypto");
// not checksummed address (will not be accepted by blockchain)
const address = "573EC96638C8BB1C386394602E1460634F02ADDA";
// checksummed ByStr20
const checksummedAddresses = toChecksumAddress(address);
// returns '0x573EC96638C8bB1c386394602E1460634F02aDdA'
const bech32_address = toBech32Address(address);
// returns zil12ulvje3ceza3cwrrj3szu9rqvd8s9tw69c978p
```
## Example Interaction Scripts
```js
//shows the javascript required to call a specific transition
node callContract.js
// shows the javascript required to create a list of signed batch transactions
node createBatchTransaction.js
//shows the javascript required to create a list of batch transactions with correct nonce
node createBatchTransactionWithoutConfirm.js
//shows the javascript required to post a raw transaction
createTransactionRaw.js
//shows the javascript required to deploy a contract
deployContract.js
//shows the javascript required to return all the particular transactions that happened for a particular block
getTxnBodiesForTxBlock.js
//shows the javascript required to interact with the helloWorld tutorial scilla
helloWorld.js
//shows the javascript required to listen for events
newEventLogSubscriptions.js
//shows the javascript required to listen for new block events
newTxBlockSubscriptions.js
//shows the javascript required to query init params, or state params including maps
queryState.js
//get a particular transaction from a given transaction hash
queryTransaction.js
//get the status of a particular transaction from a given transaction hash
queryTransactionStatus.js
//shows the javascript required to sign a unsigned batch transaction
signBatchTransaction.js
//shows examples of offline and online signs
walletSign.js
```
## zilliqa-js Interaction Examples
### zilliqa-js Examples
[zilliqa-js Example Interaction](https://github.com/Zilliqa/Zilliqa-JavaScript-Library-Examples/tree/master/node)
### TheDrBee contract Interactions
[zilliqa-js contract Interaction](https://github.com/TheDrBee/oSCILLAtor/tree/main/js)
### Zilpay Repositories
[Zilpay Browser Extension](https://github.com/zilpay/zil-pay)