arch3.js

arch3.js is an all-in-one library to interact with the Archway Protocol. It extends CosmJS CosmWasm Stargate clients' functionalities to connect with Archway's reward system. It automatically calculates the network's minimum consensus fee and contract premiums before broadcasting transactions to the chain.

This package is not a replacement for CosmJS and is intended to work in conjunction with the other modules available in @cosmjs/*.

Installation

NPM

npm install --save @archwayhq/arch3.js

Yarn

yarn add @archwayhq/arch3.js

Documentation

For a complete reference on the classes and methods available, please check the API docs.

Compatibility table

List of Archway protocol versions compatible with arch3.js:

| archwayd | arch3.js | | :----------------: | :----------------: | | >=6.0.0 | >=0.6.0 | | 5.0.0 | 0.5.0 | | 0.5.0 to 4.0.2 | 0.2.0 to 0.4.0 | | <0.5.0 | 0.1.0 |

To query the current archwayd version running on a node, you can execute:

curl -sfL 'https://rpc.constantine.archway.tech/abci_info' | jq -r '.result.response.version'

Sample Usage

The examples suppose you deployed the increment contract template to Constantine.

You can also take a look on the test specs for more examples on how to use each of the methods available in the clients.

Query

For quering the chain, use the ArchwayClient:

import { ArchwayClient } from '@archwayhq/arch3.js';

const endpoint = 'https://rpc.constantine-3.archway.tech';
const client = await ArchwayClient.connect(endpoint);

Querying a contract

const contractAddress = 'archway14v952t75xgnufzlrft52ekltt8nsu9gxqh4xz55qfm6wqslc0spqspc5lm';
const msg = {
  get_count: {},
};
const { count } = await client.queryContractSmart(contractAddress, msg);

Querying outstanding rewards

const rewardsAddress = 'archway14v952t75xgnufzlrft52ekltt8nsu9gxqh4xz55qfm6wqslc0spqspc5lm';
const { totalRewards, totalRecords } = await client.getOutstandingRewards(aliceAddress);

Execute transactions

For signing and broadcasting transactions, create a SigningArchwayClient using a signing wallet:

import { SigningArchwayClient } from '@archwayhq/arch3.js';
import { DirectSecp256k1HdWallet } from '@cosmjs/proto-signing';

const network = {
  endpoint: 'https://rpc.constantine-3.archway.tech',
  prefix: 'archway',
};

const walletMnemonic = 'culture blossom ten thing bar ...';

const wallet = await DirectSecp256k1HdWallet.fromMnemonic(walletMnemonic, { prefix: network.prefix });
const client = await SigningArchwayClient.connectWithSigner(network.endpoint, wallet);

Executing an action in a smart contract

const accounts = await wallet.getAccounts();
const contractAddress = 'archway14v952t75xgnufzlrft52ekltt8nsu9gxqh4xz55qfm6wqslc0spqspc5lm';
const msg = {
  increment: {},
};

const { transactionHash } = await client.execute(accounts[0].address, contractAddress, msg, 'auto');

Setting a contract metadata

const accounts = await wallet.getAccounts();
const metadata = {
  contractAddress: 'archway14v952t75xgnufzlrft52ekltt8nsu9gxqh4xz55qfm6wqslc0spqspc5lm',
  ownerAddress: accounts[0].address,
  rewardsAddress: accounts[0].address,
};

const { transactionHash } = await client.setContractMetadata(accounts[0].address, metadata, 'auto');

Withdrawing rewards

const accounts = await wallet.getAccounts();
const contractAddress = 'archway14v952t75xgnufzlrft52ekltt8nsu9gxqh4xz55qfm6wqslc0spqspc5lm';

// The address withdrawing the rewards should be the same
// as the `rewardsAddress` set in the contract metadata
const {
  transactionHash,
  rewards
} = await client.withdrawContractRewards(accounts[0].address, contractAddress, msg, 'auto');

Development

See HACKING.md.

License

This project is licensed under the Apache-2.0 License - see the LICENSE file for details.