Accessibility Rewards Documentation

Introduction

Accessibility Rewards is a partner reward mechanism designed to incentivize platforms and token farms based on user activity within their ecosystems. Rather than rewarding users directly, this system compensates partner platforms for attracting and maintaining active user engagement. The algorithm distributes rewards based on two key performance indicators:

Core Incentive Metrics

1. Volume: The total amount of user activity and participation within the ecosystem
2. Late Activity: Recent or sustained engagement, encouraging continuous participation over time

This dual-metric approach ensures that platforms driving both high transaction volumes and sustained user engagement receive proportional rewards, creating a balanced incentive structure that promotes ecosystem growth and platform quality.

How It Works

The Accessibility Rewards system tracks user TVL (Total Value Locked) changes over time across multiple partner token farms on various blockchains. The algorithm monitors user activity and calculates reward distributions to platforms based on the combination of transaction volume and temporal activity patterns.

Supported Blockchains

The system currently operates on EVM-based blockchains:

• Ethereum
• Base
• Arbitrum
• Optimism
• Unichain

Monitored Farms and Tokens

The Accessibility Rewards system currently monitors user activity across farms for the following tokens:

USDS Token Farms:

• SPK farm
• SKY farm
• Chronicle farm (Ethereum only)

sUSDS Token:

• Ethereum blockchain
• Layer 2 blockchains: Base, Arbitrum, Optimism, Unichain

sUSDC Token:

• Available across all 5 supported blockchains

Reward Output

All rewards are calculated and distributed based on their USDS value, providing a consistent denomination across all partner platforms regardless of the underlying token or blockchain.

Payment Schedule

Rewards are distributed on a monthly basis. To ensure accurate calculations, the system requires user data snapshots from the end of the previous month, which serve as the baseline for measuring TVL changes and user activity throughout the current reward period. This mechanism is designed to:

• Track TVL changes across multiple EVM-based blockchains
• Incentivize platforms to attract meaningful user participation and capital deployment
• Reward platforms that maintain consistent user engagement over time
• Create a fair distribution model where platform rewards scale with genuine user activity and TVL growth
• Foster long-term partnerships and ecosystem sustainability across multiple chains

---

Algorithm Details

Referral Code Tracking

The reward distribution is determined by tracking referral codes submitted during user transactions. These referral codes identify which platform facilitated the user's activity, ensuring rewards are attributed to the correct partner.

Tracked Events by Token

The system monitors different event types depending on the token and blockchain:

USDS Farms (Ethereum):

• Transfer
• Withdrawn
• Staked
• Referral

sUSDC (All 5 blockchains):

• Transfer
• Deposit
• Withdraw
• Referral

sUSDS (Ethereum only):

• Transfer
• Deposit
• Withdraw
• Referral

sUSDS (Layer 2: Base, Arbitrum, Optimism, Unichain):

• Transfer
• Swap (contains referral code in payload)

Note: While Deposit, Staked, Withdraw, and Withdrawn events are technically redundant (as the data can be extracted from Transfer and Referral events alone), tracking them explicitly dramatically improves code readability and maintainability.

Event Source Contract Addresses

Events are identified by their source contract addresses, with special handling for sUSDS on L2 blockchains:

sUSDS (Layer 2 blockchains):

• Transfer events: Emitted from the token contract
• Swap events: Emitted from the farm contract
• These farms require monitoring two different contract addresses

All Other Farms (USDS farms, sUSDC, sUSDS on Ethereum):

• All events are emitted from a single contract address per farm
• Events are identified solely by the farm contract address

Preventing Double Counting

Since the system tracks both Deposit/Withdraw events AND Transfer events, there is a risk of double counting the same staking or unstaking action. To prevent this:

USDS Farms, sUSDC, and sUSDS (Ethereum):

• Ignore all Transfer events to/from the 0x0000... address
• The zero address is used during minting/burning operations that are already captured by Deposit/Stake/Withdraw events
• This prevents counting the same TVL change twice

sUSDS (Layer 2 blockchains):

• Allow Transfer events to/from 0x0000... address with one condition:
  • The Transfer must NOT be followed by a Swap event in the same transaction
• If a Transfer to/from zero address AND a Swap event occur in the same transaction, ignore the Transfer event
• This handles the L2-specific flow where Swap events capture the referral attribution

Referral Code Attribution Logic

The current implementation uses a simplified attribution model:

First Referral Code Principle:

• The first referral code associated with a user captures all subsequent time-weighted rewards for that user
• Once a referral code is attributed, it remains active for all future activity from that user
• All TVL from the moment of attribution onwards is credited to that referral code

Untagged Activity:

• Deposits or stakes without an associated referral code are not separately incentivized
• If a referral code is later attributed to that user, all rewards (including for previously untagged activity) flow to that referral code from the moment of attribution

Example: If a user registers their first referral code 12345 on day 15 of the month, then referral code 12345 receives rewards for all of that user's TVL from day 15 onwards through the end of the month, or until another referral code is attributed to that user.

Event Extraction and Processing

Data Collection Method

Events are extracted using the Web3 library's getPastLogs function in combination with contract ABIs to decode the event data.

Extracted Event Data:

• transactionHash - Unique identifier for the transaction
• blockNumber - Block in which the transaction was included
• logIndex - Position of the event within the block's logs
• returnValues - Event-specific data including:
  • Token amounts
  • Referral codes (ref_code)
  • Fund owner addresses
  • Other token-specific parameters

Timestamp Resolution

Block timestamps are crucial for calculating time-weighted rewards:

1. The blockNumber from each event is used to make a separate Web3 request via getBlock
2. This retrieves the timestamp for when that block was mined
3. Block timestamps enable precise time-weighted averaging of TVL for reward calculations

This approach ensures that rewards accurately reflect not just the volume of activity, but also when that activity occurred during the reward period.

APY to Annualized Daily Rate Conversion

The system converts APY (Annual Percentage Yield) to an annualized daily rate using the following formula:

Annualized Daily Rate = 365 × (e^(ln(1 + APY) / 365) - 1)

Where:

• APY is the annual percentage yield as a decimal (e.g., 0.05 for 5%)
• e is Euler's number (approximately 2.71828)
• ln is the natural logarithm

This conversion allows for precise daily rate calculations that compound correctly over the year.

APY Rates by Partner Type

The base APY differs depending on partner classification:

Spark Partners:

• Base APY: 0.006 (0.6%)
• Valid through: End of 2025
• Identification criteria:
  • Referral codes in the range 100-999
  • All untagged activity on sUSDC farms

Note: Spark partner payments include a Spark treasury contract component that is calculated using a different methodology. See the Integration Boost documentation for details on treasury contract calculations.

Non-Spark Partners:

• Base APY: 0.004 (0.4%)
• Valid through: End of 2025 (no changes currently planned)

Time-Weighted Average TVL Calculation

Rewards for each referral code are calculated using a time-weighted average of TVL:

Referral Reward = Σ (TVL × Δt) / Seconds in Year

Where:

• TVL = Total Value Locked at a given point in time (in USDS)
• Δt = Time elapsed in seconds since the last TVL change for this user
• Seconds in Year = 31,536,000 seconds (365 days)
• Σ represents the sum across all time periods for that referral code

This formula ensures that platforms are rewarded proportionally to both the amount of TVL they attract and the duration that TVL remains in the system.

Final Reward Calculation

The final reward amount for each referral code is calculated as:

Final Reward = Time-Weighted TVL × Annualized Daily Rate

This simple multiplication combines:

• The time-weighted average TVL (measuring volume and duration)
• The annualized daily rate (converting APY to the appropriate yield rate)

The result is the total reward amount in USDS value that each platform receives for the monthly period.

---

Data Storage and External Entities

Blockchain Data Source - Alchemy

The system uses Alchemy as the primary blockchain data provider across all supported networks (Ethereum, Base, Arbitrum, Optimism, Unichain).

Alchemy Services Used:

• Event Syncing: Retrieving blockchain events via getPastLogs for all monitored contracts
• Block Data Syncing: Fetching block information including timestamps via getBlock
• Token Rates: Retrieving current token price data for:
  • USDS
  • sUSDS
  • sUSDC (uses the same rate as sUSDS)

MongoDB Database Structure

The system uses MongoDB to store event data and calculation results across several collections:

Collections

blocktimestamps

• Stores the timestamp associated with each block number for a specific network
• Enables efficient lookup of block times without repeated Web3 requests
• Key fields: blockNumber, timestamp, network

events

• Contains all tracked blockchain events (Transfer, Deposit, Withdraw, Referral, Stake, Swap, etc.)
• Stores complete event data including transaction hashes, block numbers, log indices, and return values
• Used as the source of truth for all user activity across monitored farms

referralstates

• Stores calculation results for each month
• Contains end-of-month user state snapshots including:
  • User TVL at month end
  • Last active referral code for the user
• These snapshots serve as the starting point for the following month's calculations
• Critical for continuity: If a user has no activity in the current month, their TVL and referral code from the previous month (which may have carried forward from many months back) continues to accrue rewards for the entire current month (is available in the last month always)

transactionchecks

• Contains transaction hashes associated with artificial referral codes
• Used for special integrations like CowSwap and Lazy Summer

Artificial Referral Code Attribution

Some platforms require custom logic to attribute referral codes when standard Referral events are not emitted.

CowSwap Integration

CowSwap referrals are identified by analyzing untagged transactions with Deposit events:

Identification Criteria:

• Transaction contains a Deposit event without an associated referral code
• Transaction includes a Transfer event to or from the address: 0x9008d19f58aabd9ed0d60971565aa8510560ab41

When these conditions are met, the transaction is attributed to CowSwap and stored in the transactionchecks collection.

Lazy Summer Integration

Lazy Summer referrals are identified through rebalancing activity:

Identification Criteria:

• Transaction is untagged (no referral code)
• Transaction contains a Rebalanced event from any contract

These transactions are attributed to Lazy Summer and recorded in the transactionchecks collection for proper reward distribution.

---

Event Collection Process

Cron Job Architecture

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

Cron Job Endpoints:

/cron/process-deposits-with-timestamps

• Collects events for each monitored farm (USDS farms, sUSDS, sUSDC across all blockchains)
• Syncs block timestamps for all new blocks encountered
• Stores collected data in the respective MongoDB collections

/cron/find-deposit-contract-interactions

• Identifies and marks CowSwap transactions
• Analyzes untagged Deposit events for Transfer interactions with CowSwap address
• Updates transactionchecks collection with CowSwap attributions

/cron/find-deposit-rebalanced

• Identifies and marks Lazy Summer transactions
• Scans for Rebalanced events in untagged transactions
• Updates transactionchecks collection with Lazy Summer attributions

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 farm, 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 and farms.

Storage Optimization and Data Cleanup

To maintain database efficiency, the system performs cleanup of zero-TVL user states:

Zero TVL Cleanup Logic:

• User states with 0 TVL and untagged referral codes are removed from referralstates
• Important: User states with 0 TVL but a tagged referral code are preserved
• This prevents losing referral code attribution when a user temporarily withdraws all funds

Why Preserve Tagged Zero TVL: If a user had previous activity with a referral code and then withdraws all deposits (returning to 0 TVL), the referral code must be maintained. If that user deposits again later without a new referral event, the previous referral code should still receive credit for the renewed activity.

---

Important Considerations

Sanity Checks and Validation

Validating Event Collection Completeness

During development, different cron job data collectors may fail, leading to missing events. To validate that calculations are correct:

Top Holders Comparison (sUSDS and sUSDC farms):

1. Print the top K users by TVL for a specific farm (sUSDS or sUSDC farms)
2. Compare these values with the "Holders" tab in the blockchain explorer for the underlying token on that specific blockchain
3. If you see any differences, this likely indicates missing events
4. Consider resyncing the specific time interval where data collection may have failed

Total TVL Validation (USDS farms):

USDS farms (SPK, SKY, Chronicle) do not have an on-chain list of holders in the holding contract. Instead, validate using total TVL:

1. Calculate the total TVL across all users for the specific USDS farm
2. Compare this with the total TVL holdings of the specific contract on-chain
3. Ensure your calculated total is within reasonable bounds of the on-chain contract balance
4. Significant discrepancies indicate missing events that require resyncing

Time-Weighted Average vs Month-End TVL Check:

Another symptom of missing events is when month-end eligible TVL is orders of magnitude smaller than the time-weighted average:

• Example: If month-end eligible TVL is $1M but time-weighted average is $4B USDS
• This extreme discrepancy indicates likely missing withdrawal events near month end
• Action: Recheck and resync events for that farm, especially focusing on the end of the month period

Resyncing Event Data

If missing events are detected and need to be resynced:

Resync Process:

1. Use the /cron/process-deposits-with-timestamps endpoint
2. Specify the startblock parameter for the beginning of the interval to resync
3. IMPORTANT: Do not commit the blocksyncstates during manual resync operations to avoid corrupting the sync state tracking

Resync Best Practices:

• Keep resync operations focused on either a specific farm or a specific time interval
• Avoid resyncing all farms simultaneously - this is extremely time and resource consuming
• Target your resync to the farm or time period where validation checks identified missing data
• Use the sanity checks above to pinpoint exactly which farm/period needs attention

---