@roninbuilders/contracts

Table of contents

• Why use this?
• Installation
• Quick start
• Contract structure
• Examples
  • Viem
  • Ethers.js
• Development
• Working examples
• Security considerations
• Contributing

Why use this?

All the contract addresses and ABIs come straight from the official Ronin Network Explorer API, so you know they're legit. You can import just the contracts you actually need instead of pulling in everything, which keeps your bundle size reasonable.

Everything has proper TypeScript types generated automatically. Works with whatever web3 library you're already using, whether that's viem, ethers.js, or something else. We keep adding new contracts as they get deployed and verified on the network.

You don't have to hunt down contract addresses or copy ABIs from block explorers anymore. Just import what you need and start building.

Installation

npm install --save-exact @roninbuilders/contracts
# or
pnpm add --save-exact @roninbuilders/contracts
# or
bun add --exact @roninbuilders/contracts

Use the exact flags to pin the version. This keeps your builds consistent and avoids any surprises from automatic updates.

Quick start

Import contracts individually

You need to import each contract separately. This keeps your bundle size small since you only get what you actually use.

import MY_CONTRACT from '@roninbuilders/contracts/my_contract';
// or for CommonJS
const MY_CONTRACT = require('@roninbuilders/contracts/my_contract');

No barrel imports

Don't try to import multiple contracts from the package root like import { AXIE_PROXY } from '@roninbuilders/contracts'. That would pull in everything. Instead, import each contract file directly:

import AXIE_PROXY from '@roninbuilders/contracts/axie_proxy'
import KATANA_ROUTER from '@roninbuilders/contracts/katana_router'

Contract structure

Each contract gives you the ABI, the verified address on Ronin Network, and some basic info like whether it's deprecated.

import AXIE_PROXY from '@roninbuilders/contracts/axie_proxy'

console.log(AXIE_PROXY.address) // Contract address
console.log(AXIE_PROXY.abi) // Contract ABI
console.log(AXIE_PROXY.proxy_abi) // Proxy ABI (if applicable)
console.log(AXIE_PROXY.is_deprecated) // Deprecation status

Some contracts also include a proxy ABI if they're behind a proxy pattern.

Examples

Viem integration

Here's how to use it with viem:

import { createPublicClient, http, formatEther, formatUnits } from 'viem'
import AXIE_PROXY from '@roninbuilders/contracts/axie_proxy'
import WRAPPED_ETHER from '@roninbuilders/contracts/wrapped_ether'
import USD_COIN from '@roninbuilders/contracts/usd_coin'

const client = createPublicClient({
  chain: {
    id: 2020,
    name: 'Ronin',
    network: 'ronin',
    nativeCurrency: {
      decimals: 18,
      name: 'Ronin',
      symbol: 'RON'
    },
    rpcUrls: {
      default: { http: ['https://api.roninchain.com/rpc'] },
      public: { http: ['https://api.roninchain.com/rpc'] },
    }
  },
  transport: http()
})

// Replace with an address you want to query
const address = '0xYourRoninAddressHere'

// Get RON balance
const ronBalance = await client.getBalance({ address })
console.log(`RON: ${formatEther(ronBalance)}`)

// Read WETH balance (18 decimals)
const weth = await client.readContract({
  address: WRAPPED_ETHER.address,
  abi: WRAPPED_ETHER.abi,
  functionName: 'balanceOf',
  args: [address]
})
console.log(`WETH: ${formatEther(weth)}`)

// Read Axies balance via proxy ABI (integer amount)
const axies = await client.readContract({
  address: AXIE_PROXY.address,
  abi: AXIE_PROXY.proxy_abi,
  functionName: 'balanceOf',
  args: [address]
})
console.log(`Axies: ${axies.toString()}`)

// Read USDC balance (6 decimals)
const usdc = await client.readContract({
  address: USD_COIN.address,
  abi: USD_COIN.abi,
  functionName: 'balanceOf',
  args: [address]
})
console.log(`USDC: ${formatUnits(usdc, 6)}`)

Ethers.js integration

Same thing but with ethers.js:

import { ethers, formatEther, formatUnits, Contract } from 'ethers'
import AXIE_PROXY from '@roninbuilders/contracts/axie_proxy'
import WRAPPED_ETHER from '@roninbuilders/contracts/wrapped_ether'
import USD_COIN from '@roninbuilders/contracts/usd_coin'

const provider = new ethers.JsonRpcProvider('https://api.roninchain.com/rpc')

// Replace with an address you want to query
const address = '0xYourRoninAddressHere'

// Get RON balance
const ron = await provider.getBalance(address)
console.log(`RON: ${formatEther(ron)}`)

// Get WETH balance (18 decimals)
const wethContract = new Contract(WRAPPED_ETHER.address, WRAPPED_ETHER.abi, provider)
const weth = await wethContract.balanceOf(address)
console.log(`WETH: ${formatEther(weth)}`)

// Get Axies balance via proxy ABI
const axieContract = new Contract(AXIE_PROXY.address, AXIE_PROXY.proxy_abi, provider)
const axies = await axieContract.balanceOf(address)
console.log(`Axies: ${axies.toString()}`)

// Get USDC balance with proper decimals (6)
const usdcContract = new Contract(USD_COIN.address, USD_COIN.abi, provider)
const usdc = await usdcContract.balanceOf(address)
console.log(`USDC: ${formatUnits(usdc, 6)}`)

Development

Update contracts from Ronin Explorer:

bun run update

Build the package:

bun run build

Format code:

bun run format

Working examples

Check out these examples to see how to use the package in different setups:

CommonJS example

Node.js with CommonJS and ethers.js. Shows the require() syntax and basic token balance fetching.

TypeScript example

Bun runtime with TypeScript and viem. Uses ES modules with full type safety and more advanced contract interactions.

Browser example

Web browser with JavaScript and viem bundled with Rollup. Has an interactive HTML interface with live blockchain data.

Security considerations

This package gives you contract ABIs and addresses, but you should still double check addresses before doing any transactions with real money. Smart contracts are risky by nature.

We get the data from the official Ronin Explorer, but things can change. Always verify addresses against official sources if you're doing anything important. This package comes with no warranty, so use it at your own risk.

If you're interacting with a contract you haven't used before, take a look at the contract code first to make sure it does what you expect.

Contributing

See CONTRIBUTING.md for contribution guidelines.