Phase 1: Activating TEL Issuance at the Application Layer - Stakers

[leo]

Following discussions during TAN Council Meetings, the scope of TANIP: Activating TEL Issuance at the Application Layer will be separated into two phases. The first phase focuses on staker issuance. A future TANIP will cover the Developer portion of TEL issuance at the application layer.

Abstract

This proposal implements TEL systems and issuance flows on TAN for Stakers, establishing the platform’s application layer incentive mechanisms. With 194.44M TEL in the TAN Council Safe, weekly distributions of TEL will flow to Stakers based on their share of Platform production. This initiates the unified staking model and activates essential platform adoption incentives.

Motivation

The Telcoin Platform requires active application layer participation to achieve its vision of universal mobile-enabled blockchain services. By implementing TEL issuance for stakers, we:

• Drive user adoption through staker referrals
• Foster an on-chain ecosystem aligned with natural market incentives

Specification

A. TEL Distribution Framework

• TAN Council Safe Balance: 194.44M TEL
• Weekly Distribution:
  • Stakers: 3,205,128.205 TEL
• Distribution Timing: Every Wednesday at 00:00 UTC

B. Staker Rules

• Eligibility: To qualify for TEL issuance, a user must meet all of the following conditions:

  1. Be a user of any registered TAN Developer’s application
  2. Have entered another user’s referral code within the application
  3. Have staked TEL through the application

• Allocation Formula: 3,205,128.205 TEL per week

• Basis for Income Formula:

  • Pro-rata share of:
    • Personal fees paid
    • Referred users’ fees paid

C. TAN Maximum Weekly TEL Issuance Rule:

• Throughout the entire period, total staked TEL must exceed: (Lifetime TEL issuance + Current week TEL issuance)

Technical Implementation

Staker contracts and developer staking contracts are already deployed and live on the Polygon Network.

TAN Issuance Calculation Specification

Invariants

• Stakers must both post a nonzero TEL stake && be a Referee to be eligible for rewards
• Stakers' own user fees are eligible for rewards
• Referrers are Stakers who have referred one or more Referees. They are eligible for their Referees’ user fees in addition to their own fees
• Thus, eligible users for TAN rewards issuance comprises Stakers and Referrers
• Support any custom time period, provided via input
• Referrer <-> Referee relationships will be provided by a TAN app backend doc (can also be identified by SimplePlugin::increaseClaimableBy() events)
• Rewards Caps: rewards for a given period are capped by the lowest stake held by the Staker/Referrer during the period, less rewards already earned. Ie: rewardsCap = stakeAmtTrough - cumulativePrevReward.
  An individual’s maximum reward amount must be less than or equal to their fee spend.
• As a result, historical rewards must be persisted for future rewards cap derivations
• User fees can be identified as the TEL sent to Amirx from aggregator. This fee is deducted a claimableStakeReward and then forwarded to fees safe

Note that the claimableStakeReward is a separate staking reward which accrues per swap rather than per TAN issuance period. It is derived based on the Staker’s stake amount with various percentage tiers as detailed in the Telcoin app.

Proposed Flow

1. Provide a time period for the distribution
2. Identify total amount of user fees for eligible Stakers and Referrers over the time period
3. Calculate the pro-rata share for each Staker and Referrer of total fees for the time period
4. Apply rewards caps to values derived in #3
5. Split total issuance amount for the time period along #4’s resulting capped pro-rata proportions

To accomplish the above:

Numbering refers to the spec steps above

2. Pull all transactions involving users in TAN app document and derive total sum of their user fees

   a. User fees can be identified by txs with a tel transfer to AmirX from aggregators. Must enforce aggregator as src address here to prevent unrelated/rogue txs from being included in calc
   b. Store these transactions and note their executor, fee amt, and referrer & Referee (if applicable)

Stored data structure example using Viem types:

interface RewardableTX {

txHash: 0x${string}; // bytes32

executor: 0x${string}; // address

userFee: BigInt; // uint256

user: 0x${string}; // address

referrer: null || 0x${string}; // optional address

}

3. Calculate total eligible fee sum for each eligible user (Stakers and Referrers) and its pro-rata weight against the total sum of user fees from #2

   a. Using relationships from TAN app doc:

   (eligible user’s fees + Referees’ fees)

   Remember that each tx’s user fee can be identified by the TEL amount sent to AmirX by the aggregator

   b. Assign pro-rata weight to each eligible user, based on their proportion of the total fee amount identified in #2:

   (referrerFees + RefereeFees) / totalFeeAmt

4. Calculate rewards caps for all eligible users, derived as follows:

   rewardsCap = stakeAmtTrough - cumulativePrevReward

   a. Identify referrer’s amount staked at the last final block:

   StakingModule::stakedByAt(referrer, lastFinalBlock)

   b. Identify stake changes within the period via

   StakingModule::stakeChanged(account, oldStake, newStake)

   c. If stake changes found, set referrer rewards cap as the lowest stake amount within the period
   d. Check historical rewards and subtract historical reward amount from rewards cap

Note that this cap results in an opportunity cost: ie funds a referrer would have earned had they staked more. The opportunity cost is intended to incentivize stakers to lock more TEL to open the door for more rewards.

Now we have calculated each referrer’s pro-rata share of total fees generated over the time period, and their current rewards cap. The final step is to apply the rewards cap.

5. Divide this period’s total issuance distribution along the pro-rata proportions derived in #3 and then apply rewards caps to output a map:

   (eligibleUser => weightedDistribution)

   a. Map is used to distribute rewards
   b. The derived weightedDistribution amount must be added to a persistent store of cumulativePrevReward which will be used in the future for #4

Example Scenario: Alice, Bob, and Charlie

To illustrate the above requirements, consider the following scenario:

Setup

• Alice is a referrer who invites Bob and Charlie to the system.

• Bob and Charlie execute trades, generating fees.

• Alice is eligible for a portion of the fees as a referrer.

Events

1. Referral Relationships

• Alice refers Bob and Charlie.

• This establishes a one-to-many relationship between Alice (referrer) and Bob/Charlie (referees).

2. Fee Generation

• Alice generates $50 in fees.

• Bob generates $100 in fees.

• Charlie generates $200 in fees.

• Total fees for Alice: $350.

3. Reimbursement Eligibility

• Alice is eligible for fees as she referred Bob and Charlie.

4. Stake and Rewards

• Assume Alice’s stake fluctuates during the reward period:

• Day 1: 50 tokens

• Day 2: 30 tokens

• Day 3: 40 tokens

• Alice’s reward cap for the period is determined by her lowest stake (30 tokens).

• If Alice previously earned 10 tokens in rewards, her new reward cap becomes:

Lowest Stake (30) - Previous Rewards (10) = 20 tokens

5. Reward Distribution

• Rewards are distributed based on Alice’s portion of total fees.

• Calculation considers the custom reward period (e.g., start time t1 to end time t2).

• Output in a blockchain friendly format

Addresses

• Executor
  • Address: 0x0082CaF47363bD42917947d81f4d4E0395257267
  • Address: 0xA64B745351EC40bdb3147FF99db2ae21cf93E6E3
  • Gas Sponsor for all trades
• Aggregator
  • Address: 0x1111111254EEB25477B68fb85Ed929f73A960582
  • Address: 0xDef1C0ded9bec7F1a1670819833240f027b25EfF
  • Performs DeFi trades
• ProxyFactory
  • Address: 0x1FF89677646bfc4189475fC4eCfC7cF7a3b10F3e
  • Address: 0x6FE6d75634E3f79B591d1B358835846b7abb6c4D
  • Can provide record of wallets
  • event Deployed(address indexed proxy, bytes32 salt)
• AmirX
  • Address: 0x4eB4A35257458C1a87A4124CE02B3329Ed6b8D5a
  • All trades are routed through contract
  • Transfer Events
  • To be Deprecated
    • 0x5c4Bb7067199f91a432Ae5F90C742967CfDF7E50
    • 0xfBBB07E82c771489f2256f82060CAB17DB14c18f
• Staking Contract
  • Address: 0x92e43Aec69207755CB1E6A8Dc589aAE630476330
  • Provides value of stake
  • event StakeChanged(address indexed account, uint256 oldStake, uint256 newStake)
• Staking Plugin
  • Address: 0xDb0e60A38Bf7d04c8ae0B396A65E5aa550f9885A
  • Rewards provided to referrer to build relationship
  • event ClaimableIncreased(address indexed account, uint256 oldClaimable, uint256 newClaimable)
  • To be Deprecated
    • 0x2f3378850a8fD5a0428a3967c2Ef6aAA025a4E1D
    • 0xe24f8d36405704e85945a639fdaCEc47bA2a7c88
• Fees Safes
  • Address: 0x8Eb6bBBF0fEe93ADC3A992d3DD54ED5294961237
  • Address: 0xd796d81170645fdd1EFC1c1b1090969B11008D9C
  • Destination address for fees
  • Transfer Events
• Wallet Implementation
  • Address: 0xb60c857742c2a93bbccb69dde3fa48a4af92db65

[robriks]

Markus (Telcoin Smart Contract Engineer) chiming in here with an exciting update.

The TANIP-1 Staker Incentives Calculator is complete and ready for the program’s imminent launch.

I’ve implemented extensive fuzz and fork tests which ensure the calculator properly calculates expected values from onchain TAN user activity simulated on a fork of Polygon. The tests simulates randomized user relationships and then performs user staking and TAN trading on a local fork chain, followed by application of the calculator to the onchain data which examines the user fees, fetches necessary events and stake + reward cap information from the chain, and finally performs the calculations according to the program rules defined below.

For a visual representation of the calculator’s end-to-end workings, here is a system diagram describing the code. The code’s repository is slated for open-sourcing soon as well so that community members will be able to run the calculator on the chain to verify that reward amounts are valid and properly distributed. This will also enable the community to run the tests to verify that the calculator works according to the spec.

We are currently backtesting the calculator on existing Polygon data to triple check functionality as well as deciding on a launch date for the program, which will be announced in the near future.

TAN Issuance Calculator Specification

Protocol Participants

• Stakers are Telcoin mobile app users who have posted nonzero TEL stake to the Telcoin StakingModule contract

• Referees are users who have supplied a referral code from another TAN user to the app

• Referrers are users who have referred one or more Referees

• Stakers are eligible for rewards based on their own user fees

• Stakers who are also Referrers are further eligible for rewards based on their Referees user fees. Note that this is in addition to the eligibility of their own user fees.

Invariants

Eligibility: Stakers must both post a nonzero TEL stake and be the beneficiary of eligible fees as defined for Protocol Participants to be eligible for issuance rewards

Stakers' own user fees are eligible for rewards if they are also Referees, and if they are Referrers they are additionally eligible for their Referees fees. As a result, the set of eligible users for TAN rewards issuance comprises both Stakers and Referrers.

Rewards Caps: Rewards for any given period are capped by the lowest stake held by the Staker/Referrer during the period, less cumulative rewards already earned.

To incentivize staking TEL, Stakers' are only eligible to receive issuance rewards up to their lowest amount staked for the period. This includes their cumulative rewards for all previous periods. Thus rewardsCap = stakeAmtTrough - cumulativePrevRewards.

Historical rewards checkpoints are persisted by the TANIssuanceHistory contract in a mapping called prevCumulativeRewards for immutable derivation of future rewards caps.

Multichain Support: The StakerIncentivesCalculator class works across multiple chains.

This is achieved by instantiating and providing each chain’s BaseBlocksDatabase, TokenTransferHistory, Aggregator set, StakingModule, TanIssuanceHistory, and AmirX contract. Data from each chain is abstracted by one degree by summing amounts to a multichain aggregate. For example, users’ total fees, stake and cumulative rewards are fetched from all chains and summed together before performing calculations.

Automatic and Manual Time Periods: The StakerIncentivesCalculator supports both automatic time period fetching from each chain as well as any custom time period accepted via CLI input.

The TANIP-1 issuance protocol makes use of a smart contract called TANIssuanceHistory, which has been designed to serve the IPlugin::increaser role for the existing implementation of Telcoin staking contracts. These are the StakingModule and its associated IPlugins.

The TANIssuanceHistory performs distribution of rewards by incrementing claimable TEL on its paired IPlugin and stores the block in which the last settlement occurred, called lastSettlementBlock.

When the StakerIncentivesCalculator is run without a specified startBlock, the calculator will automatically determine the startBlock by fetching the lastSettlementBlock from the TANIssuanceHistory for each chain.

Likewise it will automatically determine the period’s endBlock if run without a specified end block by identifying the chain’s most recent finalized block.

Onchain Referral Data: The relationships between Referrer <-> Referee are fetched from the chain on a need-to-know basis for each period.

The calculator examines all calls to AmirX::defiSwap() from Executor addresses to ensure they originated from the TAN backend and extracts the user wallet and referrer address from the transaction’s calldata. This improves performance as the calculator need only care about the referral relationships relevant for the time period.

Onchain User Fees: User fees are identified as TEL sent to AmirX from aggregators and filtered within fetchUserFeeTransfers()

To determine user fee eligibility, the calculator uses populates and iterates over a TokenTransferHistory for each chain, which contains ERC20::Transfer events for the TEL token.

Using fetchUserFeeTransfers(), it filters these down to identify transfers from the configured Aggregator addresses to the configured AmirX contracts. If these transfers were emitted as a part of an Executor transaction, these represent the user fee which may be eligible for issuance rewards if associated with a Staker or Referrer.

Executor Transactions: All legitimate user fee payments must be part of transactions initiated by the TAN backend, represented as Executor EOAs (Externally Owned Accounts)

For security, the fetchUserFeeTransfers() function also ensures that the resulting user fee transfers originated from the TAN backend. It does so by further cross referencing the user fee transfers against transactions originated by configured Executor EOAs.

For each validated user fee transfer, the fetchUserFeeTransfers() function also appends the Executor transaction’s calldata to each transfer in memory so that the User <> Referrer relationship can later be parsed.

Execution Flow

1. Determine Distribution Period:

• The application determines a startBlock and endBlock for each chain, either by accepting one input via CLI or by calling the TANIssuanceHistory contract’s lastSettlementBlock() function to automatically get the startBlock and using the chain’s most recent finalized block for endBlock.

2. Datasource and Calculator Initialization

• Initialize the datasources required for the calculator’s constructor and instantiate the calculator.

3. StakerIncentivesCalculator::fetchUserFeeTransfers()

• Identify multichain user fees over the period, defined as TEL transfer events from the DeFi aggregator address to the AmirX contract.

• Ensure all txs were initiated by executors so nobody can falsify user fees

4. StakerIncentivesCalculator::fetchOnchainData()

• Filter the fetched user fee transfers to include only those involving an eligible user fee for Stakers and Referrers.

• This necessitates fetching the trough stake amount for each transfer’s User (Wallet) and Referrer parameters over the period (located in previously appended tx calldata). It is achieved first by examining IPlugin::StakeChanged events and falling back to a direct contract read of StakingModule::stakedByAt(user, endBlock) if no events were found.

• For users and referrers who are staked, it is also necessary to fetch the users’ and referrers’ cumulative rewards, performed within processUserFeeSwaps() and processAddress()

• Returns an array comprising all eligible trades by TEL stakers & referrers as well as a map containing all eligible users for the period and their multichain reward datas (stake and cumulative rewards)

5. Derive Reward Caps

• Accrue stake amounts and cumulative rewards over multichain context and derive a final reward cap across chains for each eligible user

6. Total Fee Sum

• Identify the total sum of all user fees for all eligible Stakers and Referrers over the specified period. This is necessary for the pro-rata calculation

7. Pro-rata Calculation

• Calculate the pro-rata share for each Staker and Referrer of the total fees for the period.

• Uses a decimal scaling constant to ensure there is no potential for rounding or precision loss

8. Apply Rewards Caps:

• Apply rewards caps where applicable to values derived in step 5. If any rewards caps were applied, it will result in a remainder out of the period’s total issuance amount.

9. Distribute Issuance:

• Distribute the allocated reward amounts to each user for the period based on the capped pro-rata proportions from step 8, settling it onchain using the TANIssuanceHistory contract’s increaseClaimableByBatched() function.

• Since the TANIssuanceHistory contract serves as the Increaser role for its paired plugin, rewarded users may now claim their increased rewards from the staking contract

Relevant Addresses

Polygon Addresses

Executors

• 0x0082CaF47363bD42917947d81f4d4E0395257267

• 0xA64B745351EC40bdb3147FF99db2ae21cf93E6E3

Aggregator

• The Telcoin Application Network utilizes 1inch and 0x aggregators for DeFi trades:

• 0x1111111254EEB25477B68fb85Ed929f73A960582

• 0xDef1C0ded9bec7F1a1670819833240f027b25EfF

AmirX

• 0x4eB4A35257458C1a87A4124CE02B3329Ed6b8D5a

Staking Contract

• Locks staked TEL for all Stakers and Referrers:

• 0x92e43Aec69207755CB1E6A8Dc589aAE630476330

Staking Plugins

• SimplePlugin contracts emit ClaimableIncreased events for deriving Referrer <-> Referee relationships:

• Awaiting deployment to production

TANIssuanceHistory

• Awaiting deployment to production

[William]

@leo

An individual’s maximum reward amount must be less than or equal to their fee spend.

Hey @leo ,
I have a question regarding that statement.
If I don’t make any trade during a week but my referees do, will I earn rewards from the TAN issuance?
If I generate “only” 1k TEL in fees, will my TAN issuance be capped to 1k TEL?

Thanks for clarifying