Integration Guide

This guide walks you through deploying your own ClaimIssuer and ERC-3643 token suite on Redbelly Network, then onboarding users whose identities are verified through the Averer SDK.

All steps use the averer-tokeny-integration toolkit, a config-driven set of Hardhat scripts.

Prerequisites

Node.js and npm
A funded deployer wallet on Redbelly Network (testnet or mainnet)
Access to a Redbelly RPC endpoint
Users onboarded via the Averer Web SDK (wallet addresses and verification results)

The T-REX factory infrastructure (TREXFactory, Identity Factory) is pre-deployed on Redbelly Network. You do not need to deploy these contracts yourself.

Setup

Clone the toolkit and install dependencies:

git clone https://github.com/Averer/averer-tokeny-integration.git
cd averer-tokeny-integration
npm install

Copy the configuration templates:

cp .env.example .env
cp config/networks/testnet.json.example config/networks/testnet.json
cp config/networks/mainnet.json.example config/networks/mainnet.json
cp config/claim-issuer.json.example config/claim-issuer.json
cp config/token-suite.json.example config/token-suite.json
cp config/register-identity.json.example config/register-identity.json
cp config/manage-claim-signer.json.example config/manage-claim-signer.json
cp config/manage-claim-issuer.json.example config/manage-claim-issuer.json
cp config/manage-claims.json.example config/manage-claims.json

Environment variables

Edit .env with your deployer wallet key and RPC endpoints:

PRIVATE_KEY=0xyour_private_key
REDBELLY_TESTNET_RPC_URL=https://governors.testnet.redbelly.network
REDBELLY_TESTNET_CHAIN_ID=153
REDBELLY_MAINNET_RPC_URL=https://governors.mainnet.redbelly.network
REDBELLY_MAINNET_CHAIN_ID=151

Network config

The network config files (config/networks/testnet.json, config/networks/mainnet.json) contain the addresses of the pre-deployed T-REX infrastructure on each network:

{
  "trexFactory": "0x024A55ff80d88A62828Db3b2b438972eBe1e2D2d",
  "identityFactory": "0x1FD87d9789a6eF68475849D214A42bD9393d35e0",
  "identityImplementationAuthority": "0xfe24636c1772aC51bE051d185aAC771642B44Bb0",
  "trexImplementationAuthority": "0x53E64b1d0C5eB124BbEFf3503d679D2E634d3cf6",
  "defaultClaimIssuer": "0x2785522a85c4c6e4773F3Bf86fa7BF3623605270"
}

The testnet template ships with real addresses. For mainnet, update the addresses with the production infrastructure values.

Step 1: Deploy your ClaimIssuer

The ClaimIssuer is the contract whose signed claims will be trusted by your token. You own and control it.

Configure

Edit config/claim-issuer.json:

{
  "owner": "0xYourAdminWalletAddress",
  "initialClaimSigners": ["0xYourClaimSignerWalletAddress"]
}

Field	Description
`owner`	The management address that controls the ClaimIssuer. Can be your deployer, a multisig, or a separate admin wallet.
`initialClaimSigners`	Wallet addresses whose signatures produce valid claims. These can differ from the owner. You can add multiple signers.

A common pattern is for the owner to be an admin or treasury wallet, while one or more separate backend service wallets are added as claim signers.

Deploy

npm run deploy:claim-issuer:testnet

Or for mainnet:

npm run deploy:claim-issuer:mainnet

The deployed ClaimIssuer address is saved to deployments/<network>/. Copy this address -- you will need it for the next step.

Step 2: Deploy your Token Suite

This step deploys a full ERC-3643 token suite through the pre-deployed TREXFactory, including the Security Token, Identity Registry, Trusted Issuers Registry, Claim Topics Registry, and Compliance Contract.

Configure

Edit config/token-suite.json:

{
  "salt": "my-security-token-001",
  "owner": "0xYourAdminWalletAddress",
  "token": {
    "name": "My Security Token",
    "symbol": "MST",
    "decimals": 18,
    "identityRegistryStorage": "0x0000000000000000000000000000000000000000",
    "onchainId": "0x0000000000000000000000000000000000000000",
    "irAgents": ["0xYourOperatorWalletAddress"],
    "tokenAgents": ["0xYourOperatorWalletAddress"],
    "complianceModules": [],
    "complianceSettings": []
  },
  "claims": {
    "topics": [1, 2],
    "issuers": [
      {
        "address": "0xYourClaimIssuerFromStep1",
        "claimTopics": [1, 2]
      }
    ]
  }
}

Field	Description
`salt`	A unique identifier for this deployment. Must be different for each token you deploy.
`owner`	Final owner of all suite contracts. Controls registries, compliance, and token operations post-deployment. Can be your deployer, a multisig, or another admin address.
`token.name`, `token.symbol`, `token.decimals`	Standard token metadata.
`token.identityRegistryStorage`	Set to the zero address to let the factory create a new one. Set to an existing address only if you want to reuse a shared storage contract.
`token.onchainId`	Set to the zero address to let the factory create a new token ONCHAINID.
`token.irAgents`	Addresses with agent permissions on the Identity Registry. These can register user identities.
`token.tokenAgents`	Addresses with agent permissions on the token. These can mint, burn, and manage tokens.
`token.complianceModules`	Optional compliance module contract addresses.
`token.complianceSettings`	Optional encoded settings for each compliance module.
`claims.topics`	The claim topic IDs your token requires for investor verification.
`claims.issuers[].address`	Your ClaimIssuer address from Step 1.
`claims.issuers[].claimTopics`	The topics this issuer is trusted to issue.

Deploy

npm run deploy:token:testnet

Expected output includes the full suite of deployed addresses:

{
  "token": "0x...",
  "ir": "0x...",
  "irs": "0x...",
  "tir": "0x...",
  "ctr": "0x...",
  "mc": "0x..."
}

Address	Contract
`token`	Your Security Token
`ir`	Identity Registry
`irs`	Identity Registry Storage
`tir`	Trusted Issuers Registry
`ctr`	Claim Topics Registry
`mc`	Modular Compliance

These addresses are saved to deployments/<network>/. You will need the ir (Identity Registry) address for user onboarding.

Step 3: Register user identities

Each user who holds your token needs an ONCHAINID registered in the token's Identity Registry. The user's wallet address comes from their Averer Account (embedded wallet).

Configure

Edit config/register-identity.json:

{
  "identityRegistry": "0xIdentityRegistryFromStep2",
  "userAddress": "0xUsersAvererWalletAddress",
  "userIdentity": "0xUsersOnchainIdAddress",
  "country": 356
}

Field	Description
`identityRegistry`	The Identity Registry address from your token suite deployment (Step 2).
`userAddress`	The user's Averer wallet address, obtained from the SDK after authentication.
`userIdentity`	The user's ONCHAINID contract address.
`country`	ISO 3166-1 numeric country code (e.g. `356` for India, `36` for Australia).

The connected wallet must have agent permissions on the Identity Registry (irAgents from your token suite config).

Run

npm run register:identity:testnet

Step 4: Add claims to user identities

Once a user's identity is registered, you add claims to their ONCHAINID. These claims attest that the user meets your compliance requirements. You decide which claims to add based on the user's Averer verification results.

Configure

Edit config/manage-claims.json:

{
  "userIdentity": "0xUsersOnchainIdAddress",
  "avererClaimIssuer": "0xYourClaimIssuerFromStep1",
  "saltPepper": "unique-proof-reference",
  "action": "add",
  "claimTopics": [1, 2]
}

Field	Description
`userIdentity`	The user's ONCHAINID contract address.
`avererClaimIssuer`	Your ClaimIssuer contract address from Step 1.
`saltPepper`	A unique string used as a proof reference in the claim data encoding.
`action`	`"add"` to add claims, `"remove"` to revoke them.
`claimTopics`	Array of claim topic IDs to issue (e.g. `[1, 2]`).

The connected wallet must be a claim signer on the ClaimIssuer (configured in Step 1 via initialClaimSigners, or added later with the claim signer management script).

Run

npm run manage:claims:testnet

Once the user has claims matching the token's required topics from a trusted issuer, they pass isVerified() and can hold and transfer the token.

Operations

After initial deployment, you will need to manage your ClaimIssuer and token configuration over time.

Managing claim signer keys

Add or remove signer keys on an existing ClaimIssuer. Use this for key rotation, adding parallel signers, or revoking compromised keys.

Edit config/manage-claim-signer.json:

{
  "claimIssuerAddress": "0xYourClaimIssuerAddress",
  "action": "add",
  "signerAddress": "0xNewSignerWalletAddress"
}

Field	Description
`claimIssuerAddress`	The ClaimIssuer contract to manage.
`action`	`"add"` to grant claim signer permission, `"remove"` to revoke it.
`signerAddress`	The wallet address to add or remove as a claim signer.

The connected wallet must have management-key permission on the ClaimIssuer.

npm run manage:claim-signer:testnet

You can have multiple active claim signer keys on a single ClaimIssuer. If a signer wallet is lost or compromised, add the replacement signer and then remove the old key. Only signatures from addresses that currently have claim signer permission will be accepted.

Managing trusted claim issuers

Add, remove, or update trusted issuers in your token's Trusted Issuers Registry. Use this when you want to trust a new ClaimIssuer, revoke trust, or change which claim topics an issuer is allowed to issue.

Edit config/manage-claim-issuer.json:

{
  "tokenAddress": "0xYourTokenAddress",
  "action": "add",
  "claimIssuerAddress": "0xClaimIssuerToTrust",
  "claimTopics": [1, 2]
}

Field	Description
`tokenAddress`	Your deployed token contract address.
`action`	`"add"` to trust a new issuer (or update topics if already trusted), `"remove"` to revoke trust.
`claimIssuerAddress`	The ClaimIssuer contract address to add or remove.
`claimTopics`	Required when `action` is `"add"`. The claim topic IDs this issuer is allowed to issue for your token.

The connected wallet must be the owner of the token suite's Trusted Issuers Registry.

npm run manage:claim-issuer:testnet

Complete workflow summary

# 1. Setup
git clone https://github.com/Averer/averer-tokeny-integration.git
cd averer-tokeny-integration
npm install
cp .env.example .env
# Edit .env with your PRIVATE_KEY and RPC URLs
# Copy and edit all config templates

# 2. Deploy your ClaimIssuer
npm run deploy:claim-issuer:testnet
# Copy the ClaimIssuer address into config/token-suite.json

# 3. Deploy your token suite
npm run deploy:token:testnet
# Copy the Identity Registry address for user onboarding

# 4. Register a user identity
npm run register:identity:testnet

# 5. Add claims to the user
npm run manage:claims:testnet

Troubleshooting

"Connected wallet is not an agent"

The deployer wallet does not have agent permissions on the Identity Registry. Ensure the wallet address is listed in irAgents in your token suite config, or add it as an agent after deployment.

"Identity already registered"

The user's wallet address already has an ONCHAINID linked in the Identity Registry. Use the existing identity address.

Token transfers revert

Verify that the user passes compliance checks:

Confirm isVerified(userAddress) returns true on the Identity Registry.
Check that the user's claims match the required topics in the Claim Topics Registry.
Verify that the claims come from an issuer trusted in the Trusted Issuers Registry.
Ensure the claim signatures were produced by an address with active claim signer permission on the ClaimIssuer.

"Connected wallet is not the TrustedIssuersRegistry owner"

Only the owner of the Trusted Issuers Registry can add or remove trusted issuers. Use the wallet address set as owner in your token suite config.