ar.io Docs

# ar-io sdk

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

# Prerequisites

  • node>=v18.0.0
  • npm or yarn

# Installation

npm install @ar.io/sdk

or

yarn add @ar.io/sdk

# Quick Start

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

const arIO = new ArIO();
const gateways = arIO.getGateways();
Output 
{
  "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ": {
    "end": 0,
    "observerWallet": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
    "operatorStake": 250000,
    "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
      }
  },
"-RlCrWmyn9OaJ86tsr5qhmFRc0h5ovT5xjKQwySGZy0": {
  "end": 0,
  "observerWallet": "-RlCrWmyn9OaJ86tsr5qhmFRc0h5ovT5xjKQwySGZy0",
  "operatorStake": 11300,
}

# 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 (opens new window) based on your project's configuration. Refer to the examples (opens new window) directory to see how to use the SDK in various environments.

# Web

# Bundlers (Webpack, Rollup, ESbuild, etc.)

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

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

# Browser

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

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

# Node

# ESM (NodeNext)
import { ArIO } from '@ar.io/sdk/node';

// set up client
const arIO = ArIO.init();
// fetch gateways
const gateways = await arIO.getGateways();
# CJS
import { ArIO } from '@ar.io/sdk';

// set up client
const arIO = ArIO.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.

# ArIO Contract

# 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 = ArIO.init()

const browserSigner = new ArConnectSigner(window.arweaveWallet);
const arIOWriteable = ArIO.init({ signer: browserSigner});

const nodeSigner = new ArweaveSigner(JWK);
// read and write client that has access to all APIs
const arIOWriteable = ArIO.init({ signer: nodeSigner});

# getState({ evaluationOptions })

Retrieves the current state of the ArIO contract.

const arIO = ArIO.init();
const state = await arIO.getState();
Output 
{
  "lastTickedHeight": 1415568, // current block height
  "evolve": "92MCDWn0LihmWXKVnOeMDEQxPbiV4Y3bRjnTet7J3eg",
  "auctions": {
    // auctions
  },
  "balances": {
    // balances
  },
  "distributions": {
    // epoch distribution info
  },
  "gateways": {
    // gateways
  },
  "observations": {
    // observations
  },
  "prescribedObservers": {
    // prescribedObservers
  },
  "records": {
    // records
  },
  "demandFactoring": {
    // demandFactoring
  },
  "vaults": {
    // vaults
  }
}

Alternatively, you can get the contract at a specific block height or sort key by providing evaluationOptions:

const arIO = ArIO.init();
const state = await arIO.getState({
  evaluationOptions: {
    evalTo: { blockHeight: 1382230 }, // alternatively, use evalTo: { sortKey: 'SORT_KEY' }
  },
});
Output 
{
  "lastTickedHeight": 1382230, // evaluated block height
  "evolve": "92MCDWn0LihmWXKVnOeMDEQxPbiV4Y3bRjnTet7J3eg",
  "auctions": {
    // auctions
  },
  "balances": {
    // balances
  },
  "distributions": {
    // epoch distribution info
  },
  "gateways": {
    // gateways
  },
  "observations": {
    // observations
  },
  "prescribedObservers": {
    // prescribedObservers
  },
  "records": {
    // records
  },
  "demandFactoring": {
    // demandFactoring
  },
  "vaults": {
    // vaults
  }
}

# getBalance({ address, evaluationOptions })

Retrieves the balance of the specified wallet address.

const arIO = ArIO.init();
const balance = arIO.getBalance({
  address: 'INSERT_WALLET_ADDRESS',
});
Output 
0

# getBalances({ evaluationOptions })

Retrieves the balances of the ArIO contract.

const arIO = ArIO.init();
const balances = arIO.getBalances();
Output 
{
  "-4xgjroXENKYhTWqrBo57HQwvDL51mMvSxJy6Y2Z_sA": 5000,
  "-7vXsQZQDk8TMDlpiSLy3CnLi5PDPlAaN2DaynORpck": 5000,
  "-9JU3W8g9nOAB1OrJQ8FxkaWCpv5slBET2HppTItbmk": 5000,
}

# getGateway({ address, evaluationOptions })

Retrieves a gateway's info by its staking wallet address.

const arIO = ArIO.init();
const gateway = arIO.getGateway({
  address: 'INSERT_GATEWAY_ADDRESS',
});
Output 
{
  "end": 0,
  "observerWallet": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
  "operatorStake": 250000,
  "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
    }
}

# getGateways({ evaluationOptions })

Retrieves the registered gateways of the ArIO contract.

const arIO = ArIO.init();
const gateways = arIO.getGateways();
Output 
{
  "QGWqtJdLLgm2ehFWiiPzMaoFLD50CnGuzZIPEdoDRGQ": {
    "end": 0,
    "observerWallet": "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs",
    "operatorStake": 250000,
    "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
      }
},
"-RlCrWmyn9OaJ86tsr5qhmFRc0h5ovT5xjKQwySGZy0": {
  "end": 0,
  "observerWallet": "-RlCrWmyn9OaJ86tsr5qhmFRc0h5ovT5xjKQwySGZy0",
  "operatorStake": 11300,
}

# getArNSRecord({ domain, evaluationOptions })

Retrieves the record info of the specified ArNS name.

const arIO = ArIO.init();
const record = arIO.getArNSRecord({ domain: 'ardrive' });
Output 
{
  "contractTxId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
  "endTimestamp": 1711122739,
  "startTimestamp": 1694101828,
  "type": "lease",
  "undernames": 100
}

# getArNSRecords({ evaluationOptions })

Retrieves all registered ArNS records of the ArIO contract.

const arIO = ArIO.init();
const records = arIO.getArNSRecords();
Output 
{
  "ardrive": {
    "contractTxId": "bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM",
    "endTimestamp": 1711122739,
    "startTimestamp": 1694101828,
    "type": "lease",
    "undernames": 100
  },
  "ar-io": {
    "contractTxId": "eNey-H9RB9uCdoJUvPULb35qhZVXZcEXv8xds4aHhkQ",
    "purchasePrice": 17386.717520731843,
    "startTimestamp": 1706747215,
    "type": "permabuy",
    "undernames": 10
  }
}

# getObservations({ evaluationOptions })

Returns the epoch-indexed observation list.

const arIO = ArIO.init();
const observations = await arIO.getObservations();
Output 
{
    "1350700": {
      "failureSummaries": {
        "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
        ...
        ],
     "reports": {
        "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4",
        "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA": "7tKsiQ2fxv0D8ZVN_QEv29fZ8hwFIgHoEDrpeEG0DIs",
        "osZP4D9cqeDvbVFBaEfjIxwc1QLIvRxUBRAxDIX9je8": "aatgznEvC_UPcxp1v0uw_RqydhIfKm4wtt1KCpONBB0",
        "qZ90I67XG68BYIAFVNfm9PUdM7v1XtFTn7u-EOZFAtk": "Bd8SmFK9-ktJRmwIungS8ur6JM-JtpxrvMtjt5JkB1M"
      }
}

# getDistributions({ evaluationOptions })

Returns the current rewards distribution information. The resulting object is pruned, to get older distributions use the evaluationOptions to evalTo a previous state.

const arIO = ArIO.init();
const distributions = await arIO.getDistributions();
Output 
{
    epochEndHeight: 1382379,
    epochPeriod: 43,
    epochStartHeight: 1381660,
    epochZeroStartHeight: 1350700,
    nextDistributionHeight: 1382394
}

# getEpoch({ evaluationOptions })

Returns the epoch data for the specified block height.

const arIO = ArIO.init();
const epoch = await arIO.getEpoch({ blockHeight: 1382230 });
Output 
{
    epochStartHeight: 1381660,
    epochEndHeight: 1382379,
    epochZeroStartHeight: 1350700,
    epochDistributionHeight: 1382394,
    epochPeriod: 43,
    epochBlockLength: 720
}

# getCurrentEpoch({ evaluationOptions })

Returns the current epoch data.

const arIO = ArIO.init();
const epoch = await arIO.getCurrentEpoch();
Output 
{
    epochStartHeight: 1381660,
    epochEndHeight: 1382379,
    epochZeroStartHeight: 1350700,
    epochDistributionHeight: 1382394,
    epochPeriod: 43,
    epochBlockLength: 720
}

# getPrescribedObservers({ evaluationOptions })

Retrieves the prescribed observers of the ArIO contract. To fetch prescribed observers for a previous epoch set the evaluationOptions to the desired epoch.

const arIO = ArIO.init();
const observers = arIO.getPrescribedObservers();
Output 
[
  {
    "gatewayAddress": "BpQlyhREz4lNGS-y3rSS1WxADfxPpAuing9Lgfdrj2U",
    "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
    "stake": 10000,
    "start": 1296976,
    "stakeWeight": 1,
    "tenureWeight": 0.41453703703703704,
    "gatewayRewardRatioWeight": 1,
    "observerRewardRatioWeight": 1,
    "compositeWeight": 0.41453703703703704,
    "normalizedCompositeWeight": 0.0018972019546783507
  },
]

// observers from a previous epoch
const previousEpochObservers = arIO.getPrescribedObservers({
  evaluationOptions: {
    evalTo: { blockHeight: 1296975 }, // some block height from a previous epoch
  },
});

[
  {
    "gatewayAddress": "2Ic0ZIpt85tjiVRaD_qoTSo9jgT7w0rbf4puSTRidcU",
    "observerAddress": "2Ic0ZIpt85tjiVRaD_qoTSo9jgT7w0rbf4puSTRidcU",
    "stake": 10000,
    "start": 1292450,
    "stakeWeight": 1,
    "tenureWeight": 0.4494598765432099,
    "gatewayRewardRatioWeight": 1,
    "observerRewardRatioWeight": 1,
    "compositeWeight": 0.4494598765432099,
    "normalizedCompositeWeight": 0.002057032496835938
  },
]

# getAuction({ domain, evaluationOptions })

Return the auction info for the supplied domain, be it in auction, registered, or available to auction.

const auction = await arIO.getAuction({ domain });
Output 
 {
  "name": "ardrive",
  "initiator": "",
  "contractTxId": "",
  "startPrice": 89950,
  "floorPrice": 1799,
  "startHeight": 1384196,
  "endHeight": 1394276,
  "type": "lease",
  "years": 1,
  "isActive": false,
  "isAvailableForAuction": false,
  "isRequiredToBeAuctioned": false,
  "currentPrice": 1799,
  "prices": {
    "1384196": 89950,
    "1384226": 88930,
    "1384256": 87922,
    ...
    "1394216": 1921,
    "1394246": 1899,
    "1394276": 1877
  }
}

# getAuctions({ evauluationOptions })

Retrieves all active auctions.

const auctions = await arIO.getAuctions({ evaluationOptions });
Output 
{
  "cyprien": {
    "contractTxId": "Fmhdc4f1rWK6Zn1W__7GNvWvo4d1FSze7rLK5AOnO5E",
    "endHeight": 1386879,
    "floorPrice": 4758777913,
    "initiator": "UPJHTNsaKcC6baqLFHMAMI7daWPIG3NDDfFQ2s2h8T0",
    "startHeight": 1376799,
    "startPrice": 237938895627,
    "type": "permabuy"
  },
  "saktinaga": {
    "contractTxId": "nl8heYyDxKowujaDqbsPkjALzULYG8T0z3J91CdWDIM",
    "endHeight": 1386834,
    "floorPrice": 2379388956,
    "initiator": "TE0zVR32RF5qFAO8K50-pEivZpM_s35HK-dex-5d-IU",
    "startHeight": 1376754,
    "startPrice": 118969447813,
    "type": "permabuy"
  }
}

# joinNetwork( params )

Joins a gateway to the ar.io network via its associated wallet. Requires signer to be provided on ArIo.init to sign the transaction.

const jointNetworkParams = {
  /* initial operator stake */
  qty: 10000,
  /* delegated staking settings */
  allowDelegatedStaking: true,
  minDelegatedStake: 100,
  delegateRewardShareRatio: 1,
  autoStake: true,
  /* gateway metadata info */
  label: 'john smith', // min 1, max 64 characters
  note: 'The example gateway', // max 256 characters
  properties: 'FH1aVetOoulPGqgYukj0VE0wIhDy90WiQoV3U2PeY44', // Arweave transaction ID containing additional properties of the Gateway.
  observerWallet: '0VE0wIhDy90WiQoV3U2PeY44FH1aVetOoulPGqgYukj', // wallet address of the observer
  /* gateway info */
  fqdn: 'example.com',
  port: 443,
  protocol: 'https',
};
const signer = new ArweaveSigner(jwk);
// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const joinNetworkTx = await authenticatedArIO.joinNetwork(joinNetworkParams);

// joinNetworkTx is an Arweave transaction.
// example:
// joinNetworkTx.id
// t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3

# updateGatewaySettings( gatewaySettings)

Writes new gateway settings to the caller's gateway configuration. Requires signer to be provided on ArIO.init to sign the transaction.

const updateGatewaySettingsParams = {
  minDelegatedStake: 100,
};

const signer = new ArweaveSigner(jwk);
// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const updateGatewaySettingsTx = await authenticatedArIO.updateGatewaySettings(
  updateGatewaySettingsParams,
);

// updateGatewaySettingsTx is an Arweave transaction.
// example:
// updateGatewaySettingsTx.id
// t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3

# increaseDelegateStake({ target, qty })

Increases the caller's stake on the target gateway. Requires signer to be provided on ArIo.init to sign the transaction.

const params = {
  target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
  qty: 100,
};

const signer = new ArweaveSigner(jwk);
// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const increaseDelegateStakeTx =
  await authenticatedArIO.increaseDelegateStake(params);

// increaseDelegateStakeTx is an Arweave transaction.
// example:
// increaseDelegateStakeTx.id
// fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3

# decreaseDelegateStake({ target, qty })

Decrease the caller's stake on the target gateway. Requires signer to be provided on ArIo.init to sign the transaction.

const params = {
  target: 't4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3',
  qty: 100,
};

const signer = new ArweaveSigner(jwk);
// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const decreaseDelegateStakeTx =
  await authenticatedArIO.decreaseDelegateStake(params);

// decreaseDelegateStakeTx is an Arweave transaction.
// example:
// decreaseDelegateStakeTx.id
// fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3

# increaseOperatorStake({ qty })

Increases the caller's operator stake. Must be executed with a wallet registered as a gateway operator. Requires signer to be provided on ArIo.init to sign the transaction.

const params = {
  qty: 100,
};

const signer = new ArweaveSigner(jwk);
// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const increaseOperatorStakeTx =
  await authenticatedArIO.increaseOperatorStake(params);

// increaseOperatorStakeTx is an Arweave transaction.
// example:
// increaseOperatorStakeTx.id
// fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3

# decreaseOperatorStake({ qty })

Decreases the caller's operator stake. Must be executed with a wallet registered as a gateway operator. Requires signer to be provided on ArIo.init to sign the transaction.

const params = {
  qty: 100,
};

const signer = new ArweaveSigner(jwk);
// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const decreaseOperatorStakeTx =
  await authenticatedArIO.decreaseOperatorStake(params);

// decreaseOperatorStakeTx is an Arweave transaction.
// example:
// decreaseOperatorStakeTx.id
// fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3

# saveObservations({ reportTxId, failedGateways })

Saves the observations of the current epoch. Requires signer to be provided on ArIo.init to sign the transaction.

const params = {
  reportTxId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
  failedGateways: ['t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3'],
};

const signer = new ArweaveSigner(jwk);
// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const saveObservationsTx = await authenticatedArIO.saveObservations(params);

// saveObservationsTx is an Arweave transaction.
// example:
// saveObservationsTx.id
// fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3

# transfer({ target, qty, denomination })

Transfers IO or mIO depending on the denomination selected, defaulting as IO, to the designated target recipient address. Requires signer to be provided on ArIo.init to sign the transaction.

// signer required for write interactions APIs
const authenticatedArIO = ArIO.init({ signer });
const decreaseOperatorStakeTx = await authenticatedArIO.transfer({
  target: '-5dV7nk7waR8v4STuwPnTck1zFVkQqJh5K9q9Zik4Y5',
  qty: 1000,
});

# Custom Contracts

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

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

// provide a custom contract to the client, and specify local evaluation using warp
const localCustomArIO = ArIO.init({
  contract: new WarpContract<ArIOState>({
    contractTxId: 'TESTNET_CONTRACT_TX_ID',
  }),
});

// provide a custom contract to the client, and specify local evaluation using remote cache
const remoteCacheCustomArIO = ArIO.init({
  contract: new RemoteContract<ArIOState>({
    contractTxId: 'TESTNET_CONTRACT_TX_ID',
  }),
});

# Arweave Name Tokens (ANT's)

The ANT contract client class exposes APIs relevant to compliant Arweave Name Token contracts. It can be configured to use any contract ID that adheres to the ANT contract spec. You must provide either a custom contract data provider or a contractTxId 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 browserSigner = new ArConnectSigner(window.arweaveWallet);
const ant = ANT.init({signer: browserSigner});

const nodeSigner = new ArweaveSigner(JWK);
const ant = ANT.init({signer: nodeSigner});

# getOwner({ evaluationOptions })

Returns the owner of the configured ANT contract.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const owner = await ant.getOwner();
Output 
"bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM"

# getControllers({ evaluationOptions })

Returns the controllers of the configured ANT contract.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const controllers = await ant.getControllers();
Output 
["bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM"]

# getRecords({ evaluationOptions })

Returns all records on the configured ANT contract, including the required @ record that resolve connected ArNS names.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const records = await ant.getRecords();
Output 
{
    "@": {
      "transactionId": "nOXJjj_vk0Dc1yCgdWD8kti_1iHruGzLQLNNBHVpN0Y",
      "ttlSeconds": 3600
    },
    "cn": {
      "transactionId": "_HquerT6pfGFXrVxRxQTkJ7PV5RciZCqvMjLtUY0C1k",
      "ttlSeconds": 3300
    }
  }

# transfer({ target })

Transfers ownership of the ANT to a new target address.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const recipient = 'aGzM_yjralacHIUo8_nQXMbh9l1cy0aksiL_x9M359f';
const result = await ant.transfer({ target: recipient });

# setController({ controller })

Adds a new controller to the list of approved controllers on the ANT. Controllers can set records and change the ticker and name of the ANT contract.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const controller = 'aGzM_yjralacHIUo8_nQXMbh9l1cy0aksiL_x9M359f';
const result = await ant.setController({ controller });

# removeController({ controller })

Removes a controller from the list of approved controllers on the ANT.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const controller = 'aGzM_yjralacHIUo8_nQXMbh9l1cy0aksiL_x9M359f';
const result = await ant.removeController({ controller });

# setRecord({ subDomain, transactionId, ttlSeconds })

Updates or creates a record in the ANT contract.

Records, or undernames are configured with the transactionId - the arweave transaction id the record resolves - and ttlSeconds, the Time To Live in the cache of client applications.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const subDomain = 'test-domain';
const transactionId = '432l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ttlSeconds = 900;
const result = await ant.setRecord({ subDomain, transactionId, ttlSeconds });

# removeRecord({ subDomain })

Removes a record from the ANT contract.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const subDomain = 'test-domain';
const result = await ant.removeRecord({ subDomain });

# setName({ name })

Sets the name of the ANT contract.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const name = 'chumbawumba';
const result = await ant.setName({ name });

# setTicker({ ticker })

Sets the ticker of the ANT contract.

const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
const ant = ANT.init({ contractTxId });
const ticker = 'ANT-WUMBA';
const result = await ant.setTicker({ ticker });

# Configuration

ANT clients can be configured to use custom contract evaluator. By default they will use the remote evaluator that leverages the arns-service (opens new window).

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

// provide a custom contract to the client, and specify local evaluation using warp
const warpEvaluatedANT = ANT.init({
  contract: new WarpContract<ANTState>({
    contractTxId: 'ANT_CONTRACT_TX_ID',
  }),
  signer, // signer is required when created warp-contract instances
});

// provide a custom contract to the client, and specify local evaluation using remote cache
const remoteANTContract = ANT.init({
  contract: new RemoteContract<ANTState>({
    contractTxId: 'ANT_CONTRACT_TX_ID',
    // the remote api that returns warp compliant contract evaluation
    url: 'https://api.arns.app/v1/contract',
  }),
});

# Developers

# Requirements

  • node>=v18.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 arns-service (opens new window)
  • 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.