@ar.io/sdk

This is the home of ar.io SDK. This SDK provides functionality for interacting with the ar.io ecosystem of services (e.g. gateways and observers) and protocols (e.g. ArNS and AO). It is available for both NodeJS and Web environments.

Table of Contents

• Prerequisites

• Installation

• Quick Start

• Usage

  • Web
  • Node
  • Typescript

• IOToken & mIOToken

  • Converting IO to mIO

• ArIO Process

  • APIs
    • init({ signer })
    • getState({ evaluationOptions })
    • getBalance({ address, evaluationOptions })
    • getBalances({ evaluationOptions })
    • getGateway({ address, evaluationOptions })
    • getGateways({ evaluationOptions })
    • getArNSRecord({ domain, evaluationOptions })
    • getArNSRecords({ evaluationOptions })
    • getObservations({ evaluationOptions })
    • getDistributions({ evaluationOptions })
    • getEpoch({ evaluationOptions })
    • getCurrentEpoch({ evaluationOptions })
    • getPrescribedObservers({ evaluationOptions })
    • joinNetwork(params)
    • updateGatewaySettings(gatewaySettings)
    • increaseDelegateStake({ target, qty })
    • decreaseDelegateStake({ target, qty })
    • increaseOperatorStake({ qty })
    • decreaseOperatorStake({ qty })
    • saveObservations({ reportTxId, failedGateways })
    • transfer({ target, qty, denomination })
  • Custom Processes

• Arweave Name Tokens (ANT's)

  • APIs
    • init({ signer })
    • getState({ evaluationOptions })
    • getOwner({ evaluationOptions })
    • getControllers({ evaluationOptions })
    • getRecords({ evaluationOptions })
    • transfer({ target })
    • setController({ controller })
    • removeController({ controller })
    • setRecord({ subDomain, transactionId, ttlSeconds })
    • removeRecord({ subDomain })
    • setName({ name })
    • setTicker({ ticker })
  • Configuration

• Developers

  • Requirements
  • Setup & Build
  • Testing
  • Linting & Formatting
  • Architecture

Prerequisites

• node>=v18.0.0
• npm or yarn

Installation

npm install @ar.io/sdk

or

yarn add @ar.io/sdk

Quick Start

import { IO } from '@ar.io/sdk';

const arIO = IO.init();
const gateways = await arIO.getGateways();

{
  "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ": {
    "end": 0,
    "observerWallet": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
    "operatorStake": 250000000000, // value in mIO
    "settings": {
      "fqdn": "ar-io.dev",
      "label": "AR.IO Test",
      "note": "Test Gateway operated by PDS for the AR.IO ecosystem.",
      "port": 443,
      "properties": "raJgvbFU-YAnku-WsupIdbTsqqGLQiYpGzoqk9SCVgY",
      "protocol": "https"
    },
    "start": 1256694,
    "stats": {
      "failedConsecutiveEpochs": 0,
      "passedEpochCount": 30,
      "submittedEpochCount": 30,
      "totalEpochParticipationCount": 31,
      "totalEpochsPrescribedCount": 31
    },
    "status": "joined",
    "vaults": {},
    "weights": {
      "stakeWeight": 25,
      "tenureWeight": 0.9031327160493827,
      "gatewayRewardRatioWeight": 0.96875,
      "observerRewardRatioWeight": 0.96875,
      "compositeWeight": 21.189222170982834,
      "normalizedCompositeWeight": 0.27485583057217183
    }
  }
}

Usage

The SDK is provided in both CommonJS and ESM formats and is compatible with bundlers such as Webpack, Rollup, and ESbuild. Utilize the appropriately named exports provided by this SDK's package.json based on your project's configuration. Refer to the examples directory to see how to use the SDK in various environments.

Web

Bundlers (Webpack, Rollup, ESbuild, etc.)

import { IO } from '@ar.io/sdk';

// set up client
const arIO = IO.init();
// fetch gateways
const gateways = await arIO.getGateways();

Note: polyfills are only provided when using the named @ar.io/sdk/web export (which requires moduleResolution: nodenext in tsconfig.json). If you are using the default export within a Typescript project (e.g. moduleResolution: node), you will need to provide your own polyfills - specifically crypto, fs and buffer. Refer to examples/webpack and examples/vite for references in how to properly provide those polyfills. For other project configurations, refer to your bundler's documentation for more information on how to provide the necessary polyfills.

Browser

<script type="module">
  import { IO } from 'https://unpkg.com/@ar.io/sdk';

  // set up client
  const arIO = IO.init();
  // fetch gateways
  const gateways = await arIO.getGateways();
</script>

Node

ESM (NodeNext)

import { IO } from '@ar.io/sdk/node';

// set up client
const arIO = IO.init();
// fetch gateways
const gateways = await arIO.getGateways();

CJS

import { IO } from '@ar.io/sdk';

// set up client
const arIO = IO.init();
// fetch gateways
const gateways = await arIO.getGateways();

Typescript

The SDK provides TypeScript types. When you import the SDK in a TypeScript project types are exported from ./lib/types/[node/web]/index.d.ts and should be automatically recognized by package managers, offering benefits such as type-checking and autocompletion.

IOToken & mIOToken

The ArIO process stores all values as mIO (milli-IO) to avoid floating-point arithmetic issues. The SDK provides an IOToken and mIOToken classes to handle the conversion between IO and mIO, along with rounding logic for precision.

All process interactions expect values in mIO. If numbers are provided as inputs, they are assumed to be in raw mIO values.

Converting IO to mIO

import { IOToken, mIOToken } from '@ar.io/sdk';

const ioValue = 1;
const mIOValue = new IOToken(ioValue).toMIO();
console.log(mIOValue); // 1000000 (mIO)

const mIOValue = 1_000_000;
const ioValue = new mIOToken(mIOValue).toIO();
console.log(ioValue); // 1 (IO)

ArIO Process

APIs

init({ signer })

Factory function to that creates a read-only or writeable client. By providing a signer additional write APIs that require signing, like joinNetwork and delegateStake are available. By default, a read-only client is returned and no write APIs are available.

// read-only client that has access to all read APIs
const arIOReadable = IO.init()

const arweave = Arweave.init({
  host: 'ar-io.dev',
  port: 443,
  protocol: 'https'
})
// for browser environments
const browserSigner = new ArConnectSigner(window.arweaveWallet, arweave);
const arIOWriteable = IO.init({ signer: browserSigner});

// for node environments
const nodeSigner = new ArweaveSigner(JWK);
const arIOWriteable = IO.init({ signer: nodeSigner});

Custom Processes

The ArIO client class exposes APIs relevant to the ar.io process. It can be configured to use any AO Process ID that adheres to the spec of the ar.io process. In the default case, it will automatically build and utilize a process data provider interface that is configured to point the the known ar.io mainnet process ID at construction time. You can provide custom process data provider or, alternatively, a processId to the ArIO constructor to use a different, ar.io-spec-compatible process.

// provide a custom processId to the client and default to remote evaluation
const remoteCustomArIO = IO.init({
  processId: 'TESTNET_PROCESS_ID',
});

Arweave Name Tokens (ANT's)

The ANT process client class exposes APIs relevant to compliant Arweave Name Token processes. It can be configured to use any process ID that adheres to the ANT process spec. You must provide either a custom process data provider or a processId to the ANT class constructor to use.

APIs

init({ signer })

Factory function to that creates a read-only or writeable client. By providing a signer additional write APIs that require signing, like setRecord and transfer are available. By default, a read-only client is returned and no write APIs are available.

const arweave = Arweave.init({
  host: 'ar-io.dev',
  port: 443,
  protocol: 'https'
})
// in a browser environment with ArConnect
const browserSigner = new ArConnectSigner(window.arweaveWallet, arweave);
const ant = ANT.init({
  signer: browserSigner,
  processId: 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM'
});

// in a node environment
const nodeSigner = new ArweaveSigner(JWK);
const ant = ANT.init({
  signer: nodeSigner,
  processId: 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM'
});

Configuration

ANT clients can be configured to use custom process evaluator. By default they will use the AO Testnet located at ao-testnet.xyz

// provide a processId to the client and default to remote evaluation
const remoteANT = ANT.init({
  processId: 'ANT_PROCESS_ID',
});

Developers

Requirements

• node >= 18.0.0
• npm or yarn
• docker (recommended for testing)

Setup & Build

• nvm use - use the correct node version
• yarn install - installs dependencies
• yarn build - builds web/node/bundled outputs

Testing

• yarn test:integration - runs integration tests against a local AO testnet
• yarn example:web - opens up the example web page
• yarn example:cjs - runs example CJS node script
• yarn example:esm - runs example ESM node script

Linting & Formatting

• yarn lint:check - checks for linting errors
• yarn lint:fix - fixes linting errors
• yarn format:check - checks for formatting errors
• yarn format:fix - fixes formatting errors

Architecture

• Code to interfaces.
• Prefer type safety over runtime safety.
• Prefer composition over inheritance.
• Prefer integration tests over unit tests.

For more information on how to contribute, please see CONTRIBUTING.md.