Integration Boost Documentation

Introduction

Integration Boost is a reward mechanism designed to incentivize token holding at specific partner contract addresses. Unlike Accessibility Rewards which tracks user activity across farms, Integration Boost rewards partners based on the token balance maintained in designated contract addresses.

Current Configuration

Monitored Token:

USDS

Supported Blockchains:

Solana
Ethereum
Base

Payment Schedule:

Integration Boost rewards are distributed weekly
Exception: Spark treasury component is paid monthly (see Spark Treasury section below)

Partner Distribution by Blockchain

Ethereum Partners:

Multiple partners monitored at their Ethereum contract addresses

Base Partners:

Partners with contract addresses on the Base L2

Solana Partners:

Partners with contract addresses on Solana
Special Case - Grove Partner:
- Grove Partner is an artificial Grove partner on Solana but TVL is monitored through an Ethereum bridge contract
- Grove Partner's final reward calculation: Grove PArtner IB rewards minus the sum of all other Solana partner rewards
- This ensures Grove Partner receives the residual after other Solana partners are paid

How It Works

Integration Boost rewards partners based on the token balance maintained at their contract addresses over time. The system uses a time-weighted approach to ensure rewards are proportional to both the amount held and the duration of holding.

Algorithm Details

Event-Based Balance Tracking

Since the number of monitored addresses is relatively small, Integration Boost uses an efficient tracking mechanism:

Process:

Monitor Transfer events for all partner contract addresses
Extract the blockNumber for each Transfer event
Query the token balance (balanceOf) at each of those specific block numbers
Calculate time-weighted rewards based on balance changes over time

Key Advantage: This approach eliminates the need to rely on previous state snapshots. By querying the actual on-chain balance at each Transfer event block, the system ensures accuracy without maintaining complex state history.

Event Collection Methods

Event collection differs between EVM and Solana blockchains due to their architectural differences:

EVM Blockchains (Ethereum, Base):

Use Web3's getPastLogs function to retrieve Transfer events
Efficient filtering by contract address and event type
Standard EVM event indexing provides fast lookups

Solana:

Use getSignaturesForAddress to retrieve all signatures for the monitored address
Must iterate through signatures in reverse order to find Transfer events
Match specific Transfer signatures manually
Less efficient than EVM event retrieval due to Solana's different transaction/event model
Requires more processing to extract the relevant Transfer data

Despite the efficiency difference, both methods achieve the same goal: identifying all balance-changing events for time-weighted calculations.

Time-Weighted Balance Calculation

Similar to Accessibility Rewards, Integration Boost uses time-weighting to calculate rewards:

Time-Weighted Balance = Σ (Balance × Δt) / Seconds in Period

Where:

Balance = Token balance at the contract address (in USDS)
Δt = Time elapsed in seconds until the next balance change
Seconds in Period = Total seconds in the reward period (typically one year)
Σ represents the sum across all balance change periods

SSR (Sky Savings Rate) Parameter

Unlike Accessibility Rewards which uses a fixed APY, Integration Boost uses a dynamic rate parameter called SSR (Sky Savings Rate):

SSR Source:

Retrieved on-chain from contract: 0xa3931d71877c0e7a3148cb7eb4463524fec27fbd (sUSDS farm address)
The SSR value can change over time

Monitoring SSR Changes:

Track File events on the sUSDS farm contract
File events indicate when the SSR parameter has been updated
Important: Record the blockNumber when each SSR change occurs
The system must capture these changes to apply the correct rate for each time period

Handling Mid-Cycle SSR Changes:

When the SSR changes during a reward cycle, calculations must be split:

Apply the old SSR rate for time-weighted balances before the change block number
Apply the new SSR rate for time-weighted balances after the change block number
This ensures accurate reward calculations that reflect the actual rates in effect during each period

Rate Application: The time-weighted balance is multiplied by the applicable SSR rate(s) to calculate the final reward amount. If SSR changed during the period, multiple rate applications are performed for their respective time segments.

Pending Clarification: The current implementation uses SSR directly (not annualized) for standard Integration Boost partners. It needs to be confirmed whether SSR should be annualized for all partners, similar to the Spark Treasury approach.

Spark Treasury

The Spark Treasury is a special component of Spark partner payments that uses a modified calculation methodology.

Key Differences from Standard Integration Boost

Payment Schedule:

Paid monthly (unlike standard IB which is paid weekly)

Rate Calculation: The Spark Treasury uses a compound rate structure:

Annualized SSR: The SSR is converted to an annualized daily rate (same formula as Accessibility Rewards)
- Annualized Daily Rate = 365 × (e^(ln(1 + SSR) / 365) - 1)
Additional Fixed Rate: Add 0.006 (0.6%) to the annualized SSR
- This additional rate is not annualized - it's applied directly as 0.006
- Valid through: End of 2025

Final Rate Formula: Spark Treasury Rate = Annualized SSR + 0.006

Calculation

The time-weighted balance for the Spark Treasury contract is multiplied by the Spark Treasury Rate to determine the monthly reward amount.

Data Storage and External Entities

Blockchain Data Source - Alchemy

Integration Boost uses Alchemy as the primary blockchain data provider for EVM chains (Ethereum and Base).

Alchemy Services Used:

Event Retrieval: Fetching Transfer events via getPastLogs for monitored contract addresses
Block Data: Retrieving block information including timestamps
Balance Queries: Fetching token balances (balanceOf) at specific block numbers

Note: Solana data is retrieved using Solana-specific RPC methods (getSignaturesForAddress), not through Alchemy.

MongoDB Database Structure

Integration Boost uses MongoDB to store event data and calculation results across several collections:

Collections

transferevents

Contains information about blocks where TVL changed for monitored partner addresses
Stores data across all blockchains (Ethereum, Base, Solana)
Includes block numbers and timestamps for each Transfer event
Used to construct the time-weighted balance history

ssrEvents

Contains information about blocks where SSR (Sky Savings Rate) changed
Records the block number and new SSR value for each File event
Essential for applying correct rates during mid-cycle SSR changes

integrationboostrewards

Stores end-of-cycle reward information for weekly payment cycles
Contains calculated rewards for each partner
Used as the starting point when calculating new periods

integrationboostmonthlyrewards

Stores end-of-cycle reward information for monthly payment cycles
Used specifically for Spark Treasury calculations
Serves as the baseline when new calculation endpoints are invoked after the most recent result

failedjobs

Tracks any failures during event collection processes
Records which partner address, blockchain, and time interval failed
Implements automatic retry logic with up to 3 retry attempts
Ensures data completeness despite temporary network or API issues

These collections enable the system to build upon previous calculations rather than recalculating from scratch each cycle.

Event Collection Process

Cron Job Architecture

Event collection for Integration Boost is automated through scheduled cron jobs that run every 30 minutes.

Cron Job Endpoints:

/cron/sync-ssr-events

Monitors and collects SSR (Sky Savings Rate) changes
Tracks File events on the sUSDS farm contract (0xa3931d71877c0e7a3148cb7eb4463524fec27fbd)
Records block numbers and new SSR values in the ssrEvents collection

/cron/sync-transfer-events

Collects Transfer events for monitored partner addresses on EVM chains (Ethereum, Base)
Uses Web3's getPastLogs to retrieve events efficiently
Stores transfer data and block information in the transferevents collection

/cron/sync-solana-tvl

Collects Transfer events for Solana partner addresses
Uses getSignaturesForAddress to identify transfer transactions
Processes signatures in reverse order to match Transfer events
Updates the transferevents collection with Solana transfer data

Failure Handling and Retry Logic

The system includes robust error handling to ensure data completeness:

failedjobs Collection:

Tracks any cron job failures during event collection
Records which partner address, blockchain, and time interval failed
Implements automatic retry logic with up to 3 retry attempts
Prevents data gaps from temporary network or API issues

This automated collection and retry system ensures continuous and reliable event data gathering across all supported blockchains.

Partner Configuration

Disabled Periods

Partners can be temporarily excluded from reward payments using the disabledPeriods configuration parameter.

Configuration:

Define time intervals during which a specific partner should not receive rewards
Configured per partner address in the system settings

Impact on Calculations:

Standard Partners (Ethereum, Base):

Partner receives zero rewards during disabled periods
Time-weighted balances during disabled intervals are not rewarded

Solana Partners:

Disabled partner receives zero rewards during disabled periods
Important for Grove Partner: When a Solana partner is disabled, their rewards are NOT subtracted from Grove Partner's calculation
This prevents Grove Partner from being penalized for disabled partner activity
Grove Partner 's final reward = Grove Partner IB rewards - (sum of only ACTIVE Solana partner rewards)

This ensures fair reward distribution and allows for flexible partner management without affecting other partners in the ecosystem.