Personhood

Anima Reputation SBT System Overview

This guide explains how to interact with the Anima Reputation Soulbound Token (SBT) system using Solidity functions to retrieve token metadata and query specific attributes.

Smart Contract Interaction

The Anima SBT smart contract allows you to retrieve metadata associated with a user's token, which contains information such as the reputation level and the last verification timestamp. Below are the key functions for interacting with the contract:

1. mainTokenByCollection(address account, bytes32 collection)

This function retrieves the SBT token ID associated with a specific address and collection. For the main Anima Reputation collection, use the provided collection ID.

function mainTokenByCollection(address account, bytes32 collection) public view returns (uint256)

  • Input:

  • Ethereum address (account)

  • Collection ID (bytes32)

  • Output: Token ID (uint256) linked to the user's account for the specified collection.

Main Reputation Collection

The main collection ID for the Anima Reputation system is:

0x2170459f9ebc370517e9fd1abfcf476586c10aa80121c185d406f695ef6f2d6c

If a project wants to create a custom NFT collection with a unique visual for their users, they need to contact Anima for setup. Custom collections can use their own distinct collection ID.

2. tokenURI(uint256 tokenId)

This function retrieves the metadata URL associated with a specific token ID.

function tokenURI(uint256 tokenId) public view virtual returns (string memory)
  • Input: Token ID (uint256)
  • Output: Metadata URL (string) containing the SBT's attributes and other data.

Querying the Metadata

To retrieve the metadata for a specific user in the main collection, you can combine the two functions as follows:

string memory metadata_url = tokenURI(mainTokenByCollection(user_address, collection_id));

This will return the URL of the metadata JSON file for the SBT associated with the provided user address in the specified collection.

Example of Metadata Structure

The metadata returned is in JSON format and includes various attributes related to the user's reputation.

{
  "name": "Anima Reputation",
  "image": "https://example.com/image.png",
  "attributes": [
    {
      "value": 1,
      "trait_type": "Reputation Level"
    },
    {
      "value": 1709223352,
      "trait_type": "Last Verification"
    }
  ],
  "external_url": "https://dapp.anima.io"
}

Key Metadata Fields:

  • name: The name of the reputation level (e.g., "Reputation Level #1").
  • image: URL of the image representing the reputation.
  • attributes:
  • Reputation Level: Numeric value representing the user's current reputation level.
  • Last Verification: Timestamp of the user's last verification event.
  • external_url: Link to the Anima Reputation SBT service.

Smart Contract Address

The Anima Reputation SBT smart contract is now deployed on all supported chains under the unified address:

  • 0x44f0D259B9ba7e12e31cE202dcaD1B12CB3dAAf6

Supported Chains:

  • Polygon
  • Binance Smart Chain (BNB)
  • Base
  • Linea
  • Scroll

Example: Querying Metadata in JavaScript with ethers.js

Below is an example of how to query the metadata from the Anima Reputation SBT smart contract using ethers.js, followed by fetching the metadata JSON via an HTTP call.

Step 1: Set Up ethers.js

First, install the required dependencies if you haven't done so:

npm install ethers

Step 2: Query the Smart Contract

Here's a JavaScript code example to retrieve the metadata URL and then fetch the metadata using fetch:

const { ethers } = require('ethers');
const fetch = require('node-fetch');

// Set up the provider (e.g., Infura, Alchemy, or any other Ethereum RPC provider)
const provider = new ethers.providers.JsonRpcProvider('https://mainnet.infura.io/v3/YOUR_INFURA_PROJECT_ID');

// Smart contract ABI (only the relevant functions)
const contractABI = [
  'function mainTokenByCollection(address account, bytes32 collection) view returns (uint256)',
  'function tokenURI(uint256 tokenId) view returns (string)'
];

// Unified contract address
const contractAddress = '0x44f0D259B9ba7e12e31cE202dcaD1B12CB3dAAf6';

// Main collection ID
const collectionID = '0x2170459f9ebc370517e9fd1abfcf476586c10aa80121c185d406f695ef6f2d6c';

// Initialize the contract
const contract = new ethers.Contract(contractAddress, contractABI, provider);

// User's wallet address
const userAddress = '0xYourUserAddress';

async function getMetadata() {
  try {
    // Step 1: Get the token ID for the user in the main collection
    const tokenId = await contract.mainTokenByCollection(userAddress, collectionID);
    console.log(`Token ID: ${tokenId.toString()}`);

    // Step 2: Get the metadata URL for the token ID
    const metadataURL = await contract.tokenURI(tokenId);
    console.log(`Metadata URL: ${metadataURL}`);

    // Step 3: Fetch the metadata JSON from the URL
    const response = await fetch(metadataURL);
    const metadata = await response.json();

    // Step 4: Log the fetched metadata
    console.log('Fetched Metadata:', metadata);
  } catch (error) {
    console.error('Error fetching metadata:', error);
  }
}

// Call the function to fetch metadata
getMetadata();

Explanation:

  1. Set up the provider: Connect to the Ethereum network using a provider like Infura or Alchemy.
  2. Smart contract interaction:
  • Call mainTokenByCollection with the user's address and the collectionID to retrieve the token ID for the user.
  • Call tokenURI to get the metadata URL for that token ID.
  1. Fetch metadata: Once you have the metadata URL, use fetch to retrieve and parse the metadata JSON file.
  2. Log the metadata: The fetched JSON data will include attributes like the reputation level and last verification timestamp.

How It Works: Step-by-Step

  1. Retrieve the Token ID: Call the mainTokenByCollection function with the user's address and the main collection ID to retrieve the token ID associated with their account for that collection.

  2. Fetch Metadata: Once you have the token ID, use the tokenURI function to get the metadata URL, which contains all the relevant information about the user's reputation and verification status.

  3. Query Attributes: Parse the JSON metadata file returned from the URL to extract attributes such as the user's current reputation level and the timestamp of their last verification.

Summary:

This example demonstrates how to use ethers.js to query the Anima SBT smart contract for metadata and then fetch the metadata using an HTTP request. You can easily customize the code to fit your use case, such as querying different blockchain networks or using custom NFT collections.