Skip to content
Amatsu Amatsu

Integration Boost Partner Onboarding Guide

Overview

This document provides step-by-step instructions for onboarding new integration boost partners to our TVL (Total Value Locked) monitoring system. We currently support EVM chains (Base, Ethereum) and Solana.

Supported Blockchains

  • EVM Chains: Ethereum, Base
  • Non-EVM: Solana

Database Tables Overview

To add a new partner, you'll need to interact with three main tables (using Supabase UI):

  1. partners - Core partner information
  2. addresses - Partner contract addresses
  3. partners_integration_boost_settings - TVL monitoring configuration

Step-by-Step Onboarding Process

Step 1: Add Partner Information

Using the Supabase UI, add a new record to the partners table with the partner's basic information:

  • Partner name
  • Star (important!!)
  • Network

Step 2: Add Partner Address (Optional)

If the partner has a contract address or any other relevant address, add it to the addresses table via Supabase UI:

Note: The addresses table is NOT used for TVL tracking/syncing - all tracking data is read from partners_integration_boost_settings. However, addresses may be required for other purposes such as reward payment destinations.

Step 3: Configure Integration Boost Settings

This is the critical step that enables TVL monitoring for specific tokens.

For EVM Chains (Ethereum, Base)

Add a record to partners_integration_boost_settings with the following fields:

  • partner_id: ID from the partners table
  • contract_address: Partner's contract address to monitor
  • token_address: Token address whose balance you want to track
  • additional percentage: this could be an additional percentage above SSR

How to find the required data:

  1. Contract Address: The partner's smart contract address you want to monitor
  2. Token Address: The ERC-20 token contract address
  3. Both can be found on blockchain explorers like Etherscan or Basescan

For Solana

Solana requires an additional token_account_address field:

  • partner_id: ID from the partners table
  • contract_address: Partner's contract address
  • token_address: SPL token address
  • token_account_address: The associated token account (see below for how to find)
  • additional percentage: this could be an additional percentage above SSR

Finding Solana Token Account Address

The token account address is specific to Solana and can be found using Solscan:

Method 1: Via Token Dropdown

  1. Go to the contract address on Solscan
  2. Click on the "Tokens" dropdown
  3. Select the desired token
  4. The token account address will be displayed

Method 2: Via Transfer Tab (if balance is 0)

  1. Navigate to the "Transfers" tab
  2. Find a transfer involving the required token
  3. Look under "Token Balance Change" section
  4. Click on the token account link
  5. Verify that:
    • Owner matches your contract address
    • SPL Token Address matches your token address

Example Configuration

Solana Example:

  • Contract Address: 45YnzauhsBM8CpUz96Djf8UG5vqq2Dua62wuW9H3jaJ5
  • Token Address: USDSwr9ApdHk5bvJKMjzff41FfuX8bSxdKcR81vTwcA
  • Token Account Address: 4UK1j8yymsRF2rxt1DnWVAkY3ZnojVwYNStKsD8j23wm

Data Sync Behavior

EVM Chains (Ethereum, Base)

  • Current Implementation: TVL data is synced up to a specific block number
  • Future Enhancement: Will be changed to use timestamp-based syncing (similar to Solana)
  • Supporting Other EVM Chains:
    • To add support for other EVM chains, we may need to add a specific stop block parameter (up to which data is synced)
    • This would require backend changes
    • However, if we implement timestamp-based syncing for EVM (as planned), this stop block parameter won't be necessary

Solana

  • Current Implementation: Uses timestamp-based syncing
  • Sync Range: TVL data is synced with changing block numbers up to 2 months into the past
  • This ensures comprehensive data capture for Solana-based partners
  • Solana addresses are case-sensitive

Important Notes

1. Data Flow

  • TVL Tracking: All TVL monitoring and syncing is based solely on data from partners_integration_boost_settings
  • Incentive Boost Results: Updated based on settings from the partners table
  • Addresses Table: Not used for tracking, but may be needed for other operations (e.g., reward payments)

2. Token Conversion

  • ⚠️ We support any token, but automatic conversion to USDS is NOT currently supported
  • Token balances will be tracked in their native denomination

3. Configuration Limits

  • Current Limitation: Each partner can only have ONE row in partners_integration_boost_settings
  • This limitation can be changed if requirements evolve

4. Data Sources

Verification Checklist

Before considering a partner fully onboarded, verify:

  • Partner record exists in partners table
  • Address added to addresses table (if applicable)
  • Integration boost settings configured with correct:
    • Partner ID
    • Contract address
    • Token address
    • Token account address (Solana only)
    • additional percentage
  • All addresses verified on blockchain explorer
  • For Solana: Token account ownership verified

Troubleshooting

Common Issues

  1. TVL not showing up

    • Verify all addresses are correct
    • Ensure the contract actually holds the specified token
    • Check that the chain parameter matches the actual blockchain

  2. Solana token not tracked

    • Double-check the token account address
    • Verify the token account owner matches the contract address
    • Ensure the SPL token address is correct

  3. Wrong TVL values

    • Remember: No automatic USDS conversion
    • Values are in native token units
    • Check token decimals configuration

Support

For issues or questions during onboarding:

  1. Double-check all addresses using blockchain explorers
  2. Verify database entries are correct
  3. Contact the integration team if problems persist