Testnet

The AR.IO Network Testnet allows developers to test their applications and workflows using ARIO Network features such as ArNS Names before deploying to the mainnet. The ARIO Network Testnet offers a faucet for requesting testnet ARIO tokens (tARIO). The initial version of testnet only supports registering and resolving temporary ArNS names; however, enhancements such as temporary data uploads will be added in the future. We welcome feedback for improvements and other feature requests.

Faucet

Browser UI

The ARIO Network Testnet Faucet is a service that allows developers to request testnet ARIO tokens (tARIO). It can be accessed in a browser by visiting ar://faucet.

This is the recommended way to use the faucet. To use it:

  1. Select Testnet from the network dropdown
  2. Enter your wallet address
  3. Enter the an amount of tARIO tokens (max 10000)
  4. Complete the captcha challenge
  5. Click the "Request Tokens" button

Onece complete, tARIO tokens will automatically be sent to your wallet

Using Testnet

Using the testnet is similar to using the mainnet, with a few key differences:

Using the ARIO SDK

When using the ARIO SDK, to interact with the AR.IO testnet - you can create your ARIO instance in one of two ways;

  1. Using the ARIO.tesntet() API
import { ARIO } from '@ar.io/sdk'

// uses cu.ardrive.io by default, and supports `faucet` APIs
const testnet = ARIO.testnet()

By default, this instance will leverage cu.ardrive.io for process evaluation and the recommended way to interact with testnet.

  1. Using process with ARIO_TESTNET_PROCESS_ID
import { ARIO, ARIO_TESTNET_PROCESS_ID } from '@ar.io/sdk'

const ario = ARIO.init({
  processID: ARIO_TESTNET_PROCESS_ID,
  // optionally provide your own CU_URL
})

By default, this instance will leverage community CUs managed by forward.

Note: ANTs are network-agnostic, so no additional configuration is needed when working with them.

Once configured, all SDK methods will operate on testnet instead of mainnet. For more details on configuration, see the ARIO Configuration documentation.

Accessing ArNS Names

To access ArNS names on testnet in a browser, you must use a gateway that is configured to operate on testnet instead of mainnet.

The gateway ar-io.dev is configured to operate on the ARIO Network Testnet.

Using arns.app with Testnet

arns.app is the primary graphical dApp for purchasing and managing ArNS names. To configure arns.app to operate on testnet:

  1. Click the Connect button in the top right corner to connect your wallet
  2. After connecting, click on your user profile button (which replaces the Connect button)
  3. Go to Settings
Loading image from the Permaweb via Wayfinder...
  1. Click on ArNS Registry Settings
Loading image from the Permaweb via Wayfinder...
  1. On the right side of the screen, you'll see three buttons: Devnet, Testnet, and Mainnet
  2. Click on Testnet to switch the app to operate on the testnet
Loading image from the Permaweb via Wayfinder...

The app will now operate on testnet, allowing you to purchase and manage ArNS names using testnet tokens.

Running your own Gateway with testnet

In addition to ar-io.dev - you can also elect to run your own ARIO gateway that resolves names against testnet. To do so, you need to setup your gateway by following the steps in the Linux Setup Guide or the Windows Setup Guide.

Once running, modify the .env to point ARIO testnet process id.

// .env
# ...all other env configs
IO_PROCESS_ID=agYcCFJtrMG6cqMuZfskIkFTGvUPddICmtQSBIoPdiA

Once set, restart your gateway and navigate to <your-gateway-url>/ar-io/info - you should see agYcCFJtrMG6cqMuZfskIkFTGvUPddICmtQSBIoPdiA as the process id. Your gateway will now resolve arns names stored on the ARIO tesntet process.

Restrictions

Testnet has a few primary purposes: to mimic mainnet functionality as close as possible, to provide a testing bed for upcoming network upgrades, and to provide a playground for users and developers to experiment. It is NOT intended for production purposes and should not be used as such. Test ARIO (tARIO) tokens are just that - test tokens. They have no external value, may break, and have no guarantee of continued support. tARIO tokens have no relation to mainnet $ARIO and are not a proxy for any rewards. There is no supply cap on tARIO tokens. While advanced notice will be provided whenever possible, testnet may go offline for maintenance. Likewise, test token balances and test ArNS names may be reset/nullified at any point to clean up the contract state or prepare for an upgrade.

Advanced

Integrating AR.IO Testnet in your client-side applications

If you'd like to incorporate the AR.IO faucet into your application, you can programmatically retrieve access tokens - which allow your application to request testnet tokens for your users.

To integrate:

import { ARIO, ARIOToken } from '@ar.io/sdk'

// setup testnet client;
const testnet = ARIO.testnet()

// request the captcha URL for the token, which will require a human to solve
const captchaURL = await testnet.faucet.captchaURL()

// open the captcha URL in a browser;
const captchaWindow = window.open(
  captchaUrl.captchaUrl,
  '_blank',
  'width=600,height=600',
)

// The captcha URL includes a window.parent.postMessage event that is used to send the auth token to the parent window.
// You can store the auth token in localStorage and use it to claim tokens for the duration of the auth token's expiration (default 1 hour).
window.parent.addEventListener('message', async (event) => {
  if (event.data.type === 'ario-jwt-success') {
    localStorage.setItem('ario-jwt', event.data.token)
    localStorage.setItem('ario-jwt-expires-at', event.data.expiresAt)
    // close our captcha window
    captchaWindow?.close()
    // claim the tokens using the JWT token,
    const res = await testnet.faucet
      .claimWithAuthToken({
        authToken: event.data.token,
        recipient: await window.arweaveWallet.getActiveAddress(),
        quantity: new ARIOToken(100).toMARIO().valueOf(), // 100 ARIO
      })
      .then((res) => {
        alert('Successfully claimed 100 ARIO tokens! Transaction ID: ' + res.id)
      })
      .catch((err) => {
        alert(`Failed to claim tokens: ${err}`)
      })
  }
})

// you can re-use the JWT for up to 1 hour, allowing you to request tokens for multiple wallets without having to satisfy the catpcha multiple times
if (
  localStorage.getItem('ario-jwt-expires-at') &&
  Date.now() < parseInt(localStorage.getItem('ario-jwt-expires-at') ?? '0')
) {
  const res = await testnet.faucet.claimWithAuthToken({
    authToken: localStorage.getItem('ario-jwt') ?? '',
    recipient: await window.arweaveWallet.getActiveAddress(),
    quantity: new ARIOToken(100).toMARIO().valueOf(), // 100 ARIO
  })
}