Skip to content

Latest commit

 

History

History
480 lines (356 loc) · 10.9 KB

quick-reference.md

File metadata and controls

480 lines (356 loc) · 10.9 KB
Raw

Quick Reference / Cheat Sheet

Here is a collection of the most commonly used methods within near-api-js. For more in-depth look into this library, please reference the TypeDocs.

Setup

Install

npm i near-api-js

Import

Browser:

import * as nearAPI from "near-api-js";

Node:

const nearAPI = require("near-api-js");

Key Store

Browser:

// creates keyStore using private key in local storage
// *** REQUIRES SignIn using walletConnection.requestSignIn() ***

const { keyStores } = nearAPI;
const keyStore = new keyStores.BrowserLocalStorageKeyStore();

Using a File:

// creates keyStore from a provided file
// you will need to pass the location of the .json key pair

const { keyStores } = nearAPI;
const KEY_PATH = "~./near-credentials/testnet/example-account.json";
const keyStore = new keyStores.UnencryptedFileSystemKeyStore(KEY_PATH);

Using private key string:

// creates keyStore from a private key string
// you can define your key here or use an environment variable

const { keyStores, KeyPair } = nearAPI;
const keyStore = new keyStores.InMemoryKeyStore();
const PRIVATE_KEY =
  "by8kdJoJHu7uUkKfoaLd2J2Dp1q1TigeWMG123pHdu9UREqPcshCM223kWadm";
// creates a public / private key pair using the provided private key
const keyPair = KeyPair.fromString(PRIVATE_KEY);
// adds the keyPair you created to keyStore
await keyStore.setKey("testnet", "example-account.testnet", keyPair);

Note: Key store is not required if you are not signing transactions (using view call methods on a contract)

Connect

Testnet:

const { connect } = nearAPI;

const config = {
  networkId: "testnet",
  keyStore, // optional if not signing transactions
  nodeUrl: "https://rpc.testnet.near.org",
  walletUrl: "https://wallet.testnet.near.org",
  helperUrl: "https://helper.testnet.near.org",
  explorerUrl: "https://explorer.testnet.near.org",
};
const near = await connect(config);

Mainnet:

const { connect } = nearAPI;

const config = {
  networkId: "mainnet",
  keyStore, // optional if not signing transactions
  nodeUrl: "https://rpc.mainnet.near.org",
  walletUrl: "https://wallet.mainnet.near.org",
  helperUrl: "https://helper.mainnet.near.org",
  explorerUrl: "https://explorer.mainnet.near.org",
};
const near = await connect(config);

Betanet:

const { connect } = nearAPI;

const config = {
  networkId: "betanet",
  keyStore, // optional if not signing transactions
  nodeUrl: "https://rpc.betanet.near.org",
  walletUrl: "https://wallet.betanet.near.org",
  helperUrl: "https://helper.betanet.near.org",
  explorerUrl: "https://explorer.betanet.near.org",
};
const near = await connect(config);

Localnet:

const { connect } = nearAPI;
const config = {
  networkId: "local",
  nodeUrl: "http://localhost:3030",
  walletUrl: "http://localhost:4000/wallet",
};
const near = await connect(config);

keyStore setup

Wallet

Connection

Testnet:

const { connect, keyStores, WalletConnection } = nearAPI;

const config = {
  networkId: "testnet",
  keyStore: new keyStores.BrowserLocalStorageKeyStore(),
  nodeUrl: "https://rpc.testnet.near.org",
  walletUrl: "https://wallet.testnet.near.org",
  helperUrl: "https://helper.testnet.near.org",
  explorerUrl: "https://explorer.testnet.near.org",
};

// connect to NEAR
const near = await connect(config);

// create wallet connection
const wallet = new WalletConnection(near);

Mainnet:

const { connect, keyStores, WalletConnection } = nearAPI;

const config = {
  networkId: "mainnet",
  keyStore: new keyStores.BrowserLocalStorageKeyStore(),
  nodeUrl: "https://rpc.mainnet.near.org",
  walletUrl: "https://wallet.mainnet.near.org",
  helperUrl: "https://helper.mainnet.near.org",
  explorerUrl: "https://explorer.mainnet.near.org",
};

// connect to NEAR
const near = await connect(config);

// create wallet connection
const wallet = new WalletConnection(near);

Betanet:

const { connect, keyStores, WalletConnection } = nearAPI;

const config = {
  networkId: "betanet",
  keyStore: new keyStores.BrowserLocalStorageKeyStore(),
  nodeUrl: "https://rpc.betanet.near.org",
  walletUrl: "https://wallet.betanet.near.org",
  helperUrl: "https://helper.betanet.near.org",
  explorerUrl: "https://explorer.betanet.near.org",
};

// connect to NEAR
const near = await connect(config);

// create wallet connection
const wallet = new WalletConnection(near);

Sign In

// redirects user to wallet to authorize your dApp
// this creates an access key that will be stored in the browser's local storage
// access key can then be used to connect to NEAR and sign transactions via keyStore

const signIn = () => {
  wallet.requestSignIn(
    "example-contract.testnet", // contract requesting access
    "Example App", // optional
    "http://YOUR-URL.com/success", // optional
    "http://YOUR-URL.com/failure" // optional
  );
};

Note: Sign In is not required if you are using an alternative key store to local storage or you are not signing transactions (using view call methods on a contract)

Sign Out

const signOut = () => {
  wallet.signOut();
};

Check if Signed In

if(wallet.isSignedIn()) => doSomething();

Get Authorized Account Id

// returns account Id as string
const walletAccountId = wallet.getAccountId();

Get Authorized Account Object

// returns account object for transaction signing
const walletAccountObj = wallet.account();

Account

Load Account

const near = await connect(config);
const account = await near.account("example-account.testnet");

config setup

Create Account

// creates a new account using funds from the account used to create it
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.createAccount(
  "example-account2.testnet", // new account name
  "8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc", // public key for new account
  "10000000000000000000" // initial balance for new account in yoctoNEAR
);

config setup

Delete Account

// deletes account found in the `account` object
// transfers remaining account balance to the accountId passed as an argument
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.deleteAccount("beneficiary-account.testnet");

config setup

Get Account Balance

// gets account balance
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.getAccountBalance();

config setup

Get Account details

// gets account details in terms of authorized apps and transactions
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.getAccountDetails();

config setup

Send Tokens

// sends NEAR tokens
const near = await connect(config);
const account = await near.account("sender-account.testnet");
await account.sendMoney(
  "receiver-account.testnet", // receiver account
  "1000000000000000000000000" // amount in yoctoNEAR
);

config setup

State

// gets the state of the account
const near = await connect(config);
const account = await near.account("example-account.testnet");
const response = await account.state();
console.log(response);

config setup

Deploy Contract

const near = await connect(config);
const account = await near.account("example-account.testnet");
const response = await account.deployContract(fs.readFileSync('./wasm_files/status_message.wasm'));
console.log(response);

config setup

Contract

Load Contract

Standard:

const contract = new nearAPI.Contract(
  account, // the account object that is connecting
  "example-contract.testnet",
  {
    // name of contract you're connecting to
    viewMethods: ["getMessages"], // view methods do not change state but usually return a value
    changeMethods: ["addMessage"], // change methods modify state
    sender: account, // account object to initialize and sign transactions.
  }
);

config setup

Using Wallet:

const contract = new nearAPI.Contract(
  wallet.account(), // the account object that is connecting
  "example-contract.testnet",
  {
    // name of contract you're connecting to
    viewMethods: ["getMessages"], // view methods do not change state but usually return a value
    changeMethods: ["addMessage"], // change methods modify state
    sender: wallet.Account(), // account object to initialize and sign transactions.
  }
);

config setup

Call Contract

Change Method:

await contract.method_name(
  {
    arg_name: "value", // argument name and value - pass empty object if no args required
  },
  300000000000000, // attached GAS (optional)
  1000000000000000000000000 // attached deposit in yoctoNEAR (optional)
);

View Method:

const response = await contract.view_method_name();
console.log(response);

View Method w/ Args:

const response = await contract.view_method_name({ arg_name: "arg_value" });
console.log(response);

Access Keys

Add Full Access Key

// takes public key as string for argument
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.addKey("8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc");

config setup

Add Function Access Key

// adds function access key
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.addKey(
  "8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc", // public key for new account
  "example-account.testnet", // contract this key is allowed to call (optional)
  "example_method", // methods this key is allowed to call (optional)
  "2500000000000" // allowance key can use to call methods (optional)
);

config setup

Get All Access Keys

// returns all access keys associated with an account
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.getAccessKeys();

config setup

Delete Access Key

// takes public key as string for argument
const near = await connect(config);
const account = await near.account("example-account.testnet");
await account.deleteKey("8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc");

config setup

Utils

NEAR => yoctoNEAR

// converts NEAR amount into yoctoNEAR (10^-24)

const { utils } = nearAPI;
const amountInYocto = utils.format.parseNearAmount("1");

YoctoNEAR => NEAR

// converts yoctoNEAR (10^-24) amount into NEAR

const { utils } = nearAPI;
const amountInNEAR = utils.format.formatNearAmount("1000000000000000000000000");