2 of 15

Frontend Development

Learn how to connect Secret Network contracts to a frontend.

SecretJS

Written in TypeScript and provided with type definitions.
Provides simple abstractions over core data structures.
Supports every possible message and transaction type.
Exposes every possible query type.
Handles input/output encryption/decryption for Secret Contracts.
Works in Node.js, modern web browsers and React Native.

SecretJS Templates

Connecting to Secret Network
Creating account using SecretJS
Query Secret Network
Submitting transactions
Using contracts
Wallets
SNIP-20 tokens
Consuming websocket contract events

Fullstack dApp tutorial

Getting Started with SecretJS

Learn how to install and use SecretJS.

Overview

In this tutorial you will learn how to use Secret.js to connect a web3 wallet, upload a contract, instantiate a contract, execute a contract, and query a contract, amongst other use cases! For the complete Secret.js docs, see here.

All of the following examples use the pulsar-3 testnet with LCD endpoint https://pulsar.lcd.secretnodes.com.

Public LCD endpoints can be found here for both mainnet and testnet.

Installation

Create a package.json file:

npm init -y

Then install secretJS:

npm install secretjs

Set up Secret Network Client

import { SecretNetworkClient, Wallet } from "secretjs";

const wallet = new Wallet("Your mnemonic words go here");

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://pulsar.lcd.secretnodes.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

Upload a Contract

import { SecretNetworkClient, Wallet } from "secretjs";
import * as fs from "fs";

const wallet = new Wallet("Your mnemonic words go here");

const contract_wasm = fs.readFileSync("../contract/contract.wasm");

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://pulsar.lcd.secretnodes.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

let upload_contract = async () => {
  let tx = await secretjs.tx.compute.storeCode(
    {
      sender: wallet.address,
      wasm_byte_code: contract_wasm,
      source: "",
      builder: "",
    },
    {
      gasLimit: 4_000_000,
    }
  );

  const codeId = Number(
    tx.arrayLog.find((log) => log.type === "message" && log.key === "code_id")
      .value
  );

  console.log("codeId: ", codeId);

  const contractCodeHash = (
    await secretjs.query.compute.codeHashByCodeId({ code_id: codeId })
  ).code_hash;
  console.log(`Contract hash: ${contractCodeHash}`);
};

upload_contract();

Instantiate a Contract

import { SecretNetworkClient, Wallet } from "secretjs";
import * as fs from "fs";

const wallet = new Wallet("Your mnemonic words go here");

const contract_wasm = fs.readFileSync("../contract/contract.wasm");

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://pulsar.lcd.secretnodes.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

// Add your contract codeId here
let codeId = ""

// Add your contractCodeHash here
let contractCodeHash = ""

let instantiate_contract = async () => {
//instantiate message is empty in this example. If your contract needs to be instantiated with additional variables, be sure to include them.

  const initMsg = {};
  let tx = await secretjs.tx.compute.instantiateContract(
    {
      code_id: codeId,
      sender: wallet.address,
      code_hash: contractCodeHash,
      init_msg: initMsg,
      label: "Demo" + Math.ceil(Math.random() * 10000),
    },
    {
      gasLimit: 400_000,
    }
  );

  //Find the contract_address in the logs
  const contractAddress = tx.arrayLog.find(
    (log) => log.type === "message" && log.key === "contract_address"
  ).value;

  console.log(contractAddress);
};

instantiate_contract();

Contract Migration

Learn how to do contract migration with SecretJS.

Secret Network Client Setup

import { SecretNetworkClient, Wallet } from "secretjs";

const wallet = new Wallet("Your mnemonic words go here");

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://pulsar.lcd.secretnodes.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

SecretJS Contract Migration

secretjs.tx.compute.migrateContract()

Migrate a contract's code while keeping the same address. Invokes the migrate() function on the new code.

Input: MsgMigrateContractParams

const tx = await secretjs.tx.compute.migrateContract(
  {
    sender: myAddress,
    contract_address: contractAddress,
    code_id: newCodeId,
    code_hash: codeHash, // optional but way faster
    msg: {
      migrate_state_to_new_format: {},
    },
    sent_funds: [], // optional
  },
  {
    gasLimit: 100_000,
  },
);

See here for further docs on contract migration.

Query Permits

Learn how to use query permits with SecretJS.

Secret Network Client Setup

import { SecretNetworkClient, Wallet } from "secretjs";

const wallet = new Wallet("Your mnemonic words go here");

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://pulsar.lcd.secretnodes.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

Sign a Permit and use in a query

let permit = await secretjs.utils.accessControl.permit.sign(
      accounts[0].address,
      "secret-2",
      "test",
      [contractAddress],
      ["owner", "balance"],
        false
    );

    let query = await secretjs.query.snip20.getBalance({
      contract: { address: contractAddress, codeHash },
      address: accounts[0].address,
      auth: { permit },
    });

Verify a Permit

let permit = await secretjs.utils.accessControl.permit.sign(
  accounts[0].address,
  "secret-2",
  "test",
  ["abcdef"],
  ["owner", "balance"],
    false
);

// can also use the variant "verifyNoExcept"
let result = secretjs.utils.accessControl.permit.verify(
  permit,
  accounts[0].address,
  "abcdef",
  ["owner"],
);

Learn more about Query Permits here.

SNIP721 (Secret NFTs)

Learn how to send SNIP721s with SecretJS.

Secret Network Client Setup

import { SecretNetworkClient, Wallet } from "secretjs";

const wallet = new Wallet("Your mnemonic words go here");

const secretjs = new SecretNetworkClient({
  chainId: "pulsar-3",
  url: "https://pulsar.lcd.secretnodes.com",
  wallet: wallet,
  walletAddress: wallet.address,
});

Add Minter

const addMinterMsg = await secretjs.tx.snip721.addMinter(
  {
    contract_address: contractAddress,
    msg: { add_minters: { minters: [accounts[0].address] } },
    sender: accounts[0].address,
  },
  {
    gasLimit: 100_000,
  },
);

Mint SNIP721 Token

const mintMsg = await secretjs.tx.snip721.mint(
  {
    contract_address :contractAddress,
    sender: accounts[0].address,
    msg: {
      mint_nft: {
        token_id: "1",
      },
    },
  },
  {
    gasLimit: 200_000,
  },
);

Send SNIP721 Token

const txExec = await secretjs.tx.snip721.send(
  {
    sender: secretjs.address,
    contract_address: contractAddress,
    msg: {
      send_nft: {
        contract: accounts[1].address,
        token_id: "1",
      },
    },
  },
  {
    gasLimit: 50_000,
  },
);

Add Minter and Mint in a Single Transaction

const addMinterMsg = new MsgExecuteContract({
  sender: accounts[0].address,
  contract_address: contractAddress,
  // codeHash, // Test MsgExecuteContract without codeHash
  msg: { add_minters: { minters: [accounts[0].address] } },
  sentFunds: [],
});

const mintMsg = new MsgExecuteContract({
  sender: accounts[0].address,
  contract_address: contractAddress,
  code_hash: codeHash,
  msg: {
    mint_nft: {
      token_id: "1",
      owner: accounts[0].address,
      public_metadata: {
        extension: {
          image:
            "https://scrt.network/secretnetwork-logo-secondary-black.png",
          name: "secretnetwork-logo-secondary-black",
        },
      },
      private_metadata: {
        extension: {
          image:
            "https://scrt.network/secretnetwork-logo-primary-white.png",
          name: "secretnetwork-logo-primary-white",
        },
      },
    },
  },
  sentFunds: [],
});

const tx = await secretjs.tx.broadcast([addMinterMsg, mintMsg], {
  gasLimit: 5_000_000,
});

Query Tokens with Permit

let permit = await secretjs.utils.accessControl.permit.sign(accounts[0].address, "secretdev-1", "Test", [contractAddress], ["owner"], false)

let tokens2 = await secretjs.query.snip721.GetOwnedTokens({
  contract: { address: contractAddress, codeHash },
  owner: accounts[0].address,
  auth: { permit: permit },
});

Query Tokens with Viewing Key

await secretjs.tx.snip721.setViewingKey(
  {
    contract_address: contractAddress,
    sender: accounts[0].address,
    msg: {
      set_viewing_key: {
        key: "hello",
      },
    },
  },
  {
    gasLimit: 100_000,
  },
);

    let tokens = await secretjs.query.snip721.GetOwnedTokens({
  contract: { address: contractAddress, codeHash },
  owner: accounts[0].address,
  auth: { viewer: { viewing_key: "hello", address: accounts[0].address } },
});

Understanding Feegrant allowances

An allowance in the context of the Fee Grant module is a specified amount of tokens that a granter permits a grantee to use for paying transaction fees. It should be noted that there can be only one existing fee grant allowed for a grantee and granter and self grants are not allowed.

Granter and grantee

In the allowance mechanism, there are two key players:

The Granter: The granter is the account that provides the allowance. This account will be debited whenever the grantee pays transaction fees using the allowance.
The Grantee: The grantee is the account that receives the allowance. This account can use the allowance to pay for transaction fees.

Types of allowances

There are three allowance types that can be granted:

Basic Fee Allowance: This is a simple allowance model where a granter can specify a maximum limit up to which a grantee can use tokens to pay transaction fees. The allowance can also have an expiration date after which it can no longer be used.
Periodic Fee Allowance: This allowance model is more complex and versatile. It allows the granter to set a periodic reset of the allowance, creating a recurring "budget" for the grantee. This could be used to create a daily, weekly, or monthly allowance, for example.
Allowed Msg Allowance: Creates allowance only for specified message types.

Granting and revoking allowances

Granting an allowance involves the granter sending a special type of transaction that includes information about the grantee and the details of the allowance. Once the transaction is included in a block, the allowance is active and can be used by the grantee.

Revoking an allowance is also a simple process. The granter sends a revoke transaction that includes the address of the grantee. Once this transaction is processed, the grantee can no longer use the allowance to pay fees.

Handling allowance expiry and insufficient allowance

It's important to note that allowances may have an expiry date set by the granter. Once an allowance has expired, it can no longer be used to pay for transaction fees. Grantees must be aware of their allowance expiry dates and ensure that they use their allowances before they expire.

Similarly, if an allowance is exhausted (i.e., the fees for a transaction exceed the remaining allowance), the transaction will not be processed.