Staker Snapshot and Distribution Tooling

[nothing0012]

Staker Snapshot and Distribution Tooling

Abstract

This MIP proposes the development of open-source tooling and infrastructure to enable easy access to Magic Eden staker snapshots and staking power calculations. The proposal aims to facilitate external communities and developers in distributing tokens, NFTs, or other assets to ME stakers based on their staking power.

Motivation

Currently, there is no standardized and easily accessible method for external projects to obtain snapshots of Magic Eden stakers and their respective staking power. This lack of accessibility hinders potential collaborations and community-driven initiatives that could benefit the Magic Eden ecosystem. By providing open sourced and transparent access to this data, we can foster innovation, encourage community engagement, and potentially increase the value proposition for ME stakers.

Specification

The proposed solution consists of two main components:

1. ME Foundation Website Staker Snapshot

   • Implement a dedicated section on the ME Foundation website that provides up-to-date staker snapshots.
   • Ensure the snapshot data is regularly updated and easily downloadable in common formats (e.g., CSV, JSON).

2. Open-Source CLI Tool and Sample Code

   • Develop a Command Line Interface (CLI) tool that can read from the veToken on-chain program account states.
   • Create sample code demonstrating how to interact with the veToken smart contract and calculate staking power.
   • Host the CLI tool and sample code in a public GitHub repository under the ME Foundation organization.

Technical Details

• The staker snapshot and staking power calculations will be derived directly from the veToken smart contract (https://github.com/me-foundation/vetoken).
• The CLI tool will interact with the Solana blockchain to fetch and process the relevant data.
• Implement proper error handling and rate limiting to ensure stability and prevent abuse.

Rationale

By providing official tools and infrastructure for staker snapshots, we ensure that all external projects use consistent and up-to-date data. This approach promotes fairness and transparency in any distribution events that leverage ME staker data. Additionally, by making the process open-source, we encourage community contributions and improvements to the tooling over time.

Backwards Compatibility

This proposal does not introduce any backwards incompatibilities as it is an additive feature to the existing ecosystem.

Spec

1. Verify that the website snapshot accurately reflects the current state of stakers and their staking power.
2. Ensure the Website or CLI tool can successfully fetch and process staker data from the veToken (https://github.com/me-foundation/vetoken) smart contract.
3. Test the sample code with various scenarios to confirm its accuracy and reliability.

{
  "ts": "2024-03-20T15:30:00.000Z",
  "totalUIStaked": 13791417.12,
  "totalLockups": 40812,
  "totalUIStakingPower": 52270945.73,
  "stakers": [
    {
      "wallet": "AaBbCcDdEeFfGgHhIiJjKkLlMmNnOoPpQqRrSsTtUu",
      "uiStakingPower": 400,
      "uiAmount": 100,
      "startTs": 1710945600,  // Unix timestamp (e.g., March 20, 2024)
      "endTs": 1742481600,    // Unix timestamp (e.g., March 20, 2025)
      "duration": 31536000    // Duration in seconds (1 year)
    },
    {
      "wallet": "VvWwXxYyZz11223344556677889900AaBbCcDdEe",
      "uiStakingPower": 20000.01,
      "uiAmount": 10000.00,
      "startTs": 1710945600,
      "endTs": 1726617600,
      "duration": 15672000    // Duration in seconds (6 months)
    }
  ]
}

Staking Power Calculation: https://github.com/me-foundation/vetoken/blob/main/programs/vetoken/src/states.rs#L113-L139

Implementation

1. Develop the website snapshot feature and integrate it into the ME Foundation website.
2. Create the CLI tool and sample code repository.
3. Write comprehensive documentation for both the website feature and the CLI tool.

Security & Privacy Considerations

• Ensure that the snapshot data and CLI tool only access publicly available on-chain data to maintain privacy.
• Implement rate limiting and other necessary measures to prevent potential DoS attacks on the snapshot service.

[nothing0012]

Experimental Staker Snapshot API

Quick and dirty staking snapshot API that's TTL cached every 12h. Alpha quality and can have breaking changes anytime.

https://mefoundation.com/api/trpc/staking.getStakerSnapshot?input=%7B%22json%22%3A%7B%20%22token%22%3A%20%22MEFNBXixkEbait3xn9bkm8WsJzXtVsaJEn4c8Sam21u%22,%20%22ns%22%3A%20%22acAvyneD7adS3yrXUp41c1AuoYoYRhnjeAWH9stbdTf%22%7D%7D

Implementation

Rust: Onchain staking power calculation

https://github.com/me-foundation/vetoken/blob/main/programs/vetoken/src/states.rs#L90-L139

    /*
     * Voting power is based on the target_voting_pct
     * Summary:
     * 1. Check if the lockup has expired or is invalid
     * 2. Calculate max voting power based on amount and target percentage
     * 3. Handle minimum duration case (return 100% of amount)
     * 4. Handle maximum saturation case (return max voting power)
     * 5. For durations between min and max, calculate a linear increase in voting power
     *
     *                  Voting Power
     *                   ^
     *                   |
     * Max Voting Power  |           ----
     *                   |         /
     *                   |        /
     *                   |       /
     *                   |      /
     *                   |     /
     *             100%  |    /
     *                   | ---
     *                   +---------------------> Lockup Time (EndTs - StartTs)
     *                     MinTime   MaxTime
     */
    pub fn voting_power(&self, ns: &Namespace) -> u64 {
        let now = ns.now();

        if now >= self.end_ts {
            return 0;
        }
        if self.end_ts <= self.start_ts {
            return 0;
        }

        let duration = (self.end_ts - self.start_ts) as u128;
        let max_voting_power = (self.amount as u128 * self.target_voting_pct as u128) / 100;
        if duration <= ns.lockup_min_duration as u128 {
            return self.amount; // minimal 100% of the amount
        }
        if duration >= ns.lockup_max_saturation as u128 {
            return max_voting_power.try_into().expect("should not overflow");
        }

        let amount = self.amount as u128;

        let ret = amount
            + (max_voting_power - amount) * (duration - ns.lockup_min_duration as u128)
                / ((ns.lockup_max_saturation - ns.lockup_min_duration as u64) as u128);

        ret.try_into().expect("should not overflow")
    }

Typescript: Offchain typescript code example

// calcVotingPower is a util function that's equivalent of vetoken's staking power calculation
export function calcVotingPower(
  lockupAmt: number,
  lockupStartTs: number,
  lockupEndTs: number,
  lockupMinDuration: number,
  lockupMaxSaturation: number, // max duration of lockup
  lockupTargetVotingPct: number,
  now: number, // current timestamp, in seconds
): number {
  if (now > lockupEndTs) {
    return 0;
  }
  if (lockupEndTs <= lockupStartTs) {
    return 0;
  }

  const duration = lockupEndTs - lockupStartTs;
  const maxVotingPower = (lockupAmt * lockupTargetVotingPct) / 100;
  const lockupDurationRange = lockupMaxSaturation - lockupMinDuration;
  if (duration <= lockupMinDuration) {
    return lockupAmt;
  }
  if (duration >= lockupMaxSaturation) {
    return maxVotingPower;
  }
  if (lockupDurationRange <= 0) {
    return 0;
  }
  return (
    lockupAmt +
    ((maxVotingPower - lockupAmt) * (duration - lockupMinDuration)) /
      (lockupMaxSaturation - lockupMinDuration)
  );
}