Skills/Staking Analyst

From Neo Tokyo Citizen Wiki

This page hosts the Neo Tokyo Staking Analyst skill for AI agents. To use it, fetch the raw page text via ?action=raw and take the content inside the pre blocks.

SKILL.md

# Neo Tokyo Staking Analyst

## Purpose
Analyze Neo Tokyo $BYTES staking on Ethereum mainnet: estimate yields for hypothetical or actual positions, read live pool state, and validate a staker's position against on-chain data. This is the "earn" pillar of Neo Tokyo self-sufficiency — it teaches members to compute their own numbers from the contracts instead of asking in chat. Read-only: it never signs transactions and never needs anyone's private keys.

## Privacy
Neo Tokyo is a pseudonymous community. Wallet addresses are public on the blockchain, but they are still someone's pseudonym — treat them with the same care as a real name.

- Never attempt to link a wallet address to a real-world identity, Discord handle, or any other off-chain identity. This skill works with addresses as opaque identifiers only.
- Never record, publish, or share another member's position, pending rewards, or transaction history without their explicit consent. Reading public chain data for your own analysis is fine; broadcasting someone else's is not.
- Examples and worked references use constructed hypothetical positions, never a real member's position.
- When demonstrating the validation method, use only addresses the user explicitly provides.
- The only credential this skill touches is the user's own Etherscan API key (see Auth). It is never logged, stored in files, or transmitted anywhere except the Etherscan API.

## Key contracts (Ethereum mainnet)
- **NeoTokyoStaker** `0x67e1ecfa9232e27eaf3133b968a33a9a0dca9e16` — verified source, Solidity v0.8.19, not a proxy. All staking logic lives here.
- **CTZN** `0xd37ea75dd3c499eda76304f538cbf356ed9e7ed9` — soulbound token minted when a Citizen is staked (ERC1967 proxy).
- Asset types: `0` = S1 Citizen, `1` = S2 Citizen, `2` = $BYTES, `3` = LP.

## The yield formula
A staker's daily $BYTES equals their share of the pool's daily emission, minus the treasury tax:

```
daily $BYTES = your_points × (pool_daily_emissions / pool_totalPoints) × 0.97
```

All three inputs are readable on-chain (see "Live pool state"). The formula was validated end-to-end against live stakers on Oct 14, 2026 — predicted pending rewards matched the chain to the cent.

### Points
- **S1 Citizen:** `identityPoints × vaultMultiplier × timelockMultiplier / 100 / 100`
  (`identityPoints` from `identityCreditPoints(creditYield)`; `vaultMultiplier` from `getConfiguredVaultMultiplier(vaultId)`, or the `"?"` vault entry; timelock multiplier from `timelockOptions`.)
- **S2 Citizen:** `100 × timelockMultiplier / 100`
- **$BYTES bonus** (staked into an already-staked Citizen): `amount × 100 / (200 × 1e18)` — **100 points per 200 $BYTES**, flat. The timelock multiplier does NOT apply to the $BYTES bonus.
- **Caps:** 2,000 $BYTES per vaulted S1 Citizen; 200 $BYTES per unvaulted S1 or S2 Citizen.
- **Timelock boosts (S1):** 1x / 1.25x / 1.5x / 2x / 3x for 1 / 3 / 6 / 12 / 24 months. Each timelock option is a uint256 encoding `duration_seconds << 128 | multiplier_percent` (e.g. 1 month at 1x = `0x278d00…0064`).
- A position's stored points are readable directly: `stakedS1(staker, citizenId).points`. The mapping is keyed by **citizen token ID**, not by index — get a staker's citizen IDs first via `getStakerPosition(staker, 0)`.

### Live pool state
- `getTotalEmissions(assetType, fromTimestamp)` → exact $BYTES emitted by that pool since the timestamp. Call with `now − 86400` for the current daily rate. This is measurement, not modeling — prefer it over decay assumptions.
- `pool.totalPoints` is **not** exposed by any getter. Read it from contract storage: the S1 `PoolData` struct sits at `keccak256(abi.encode(uint256(0), uint256(9)))`, and `totalPoints` is field 0. (Slot 9 derived from the storage layout: `_owner`=0, `_status`=1, `permissions`=2, `managerRight`=3, `LP`=4, `NT_STAKED_CITIZEN`=5, `VAULT_CAP`=6, `NO_VAULT_CAP`=7, `timelockOptions`=8, `_pools`=9. Calibrate against the public `timelockOptions` getter if the layout ever changes.)
- `daoTax` (field 1) = 300 → 3%.
- `getPendingPoolReward(assetType, staker)` returns `(net_reward, tax)` — use it to validate your predictions.

### Validating a prediction
For any staker, predict their pending rewards and compare with `getPendingPoolReward`:
```
RPP_now = rewardPerPoint_stored + getTotalEmissions(0, pool.lastUpdated) / pool.totalPoints
predicted_net = 0.97 × (points × RPP_now − rewardAccrued − rewardsMissed)
```
(`rewardPerPoint`, `lastUpdated` are pool fields 2–3; `rewardAccrued(staker, type)` is public; `rewardsMissed` is pool field 6, a per-address mapping.) Agreement confirms the points, emission, and tax figures are all correct.

### Finding stakers
`eth_getLogs` on the staker contract for the `Stake` event (`topic0 0x63602d0ecc7b3a0ef7ff1a116e23056662d64280355ba8031b6d0d767c4b4458`); staker address is `topic1`, asset contract is `topic2`. Filter `topic2` to the S1 Citizen contract for S1 stakers. `Claim` events (`topic0 0x34fcbac0073d7c3d388e51312faf357774904998eeb8fca628b9e6f65ee1cbf7`) show who has claimed.

## Tooling
- `eth_call` through the Etherscan V2 API (`module=proxy&action=eth_call`), or Etherscan's Read Contract tab for one-off checks.
- `eth_getStorageAt` (`module=proxy&action=eth_getStorageAt`) for pool internals like `totalPoints`.
- `eth_getLogs` (`module=logs&action=getLogs`) for Stake/Claim event scans.
- Rate discipline: 3–5 calls/second max; space calls ~0.35s apart; strictly sequential.
- keccak256 is required for storage-slot math (Ethereum Keccak, not NIST SHA3).

## Worked reference (measured on-chain, Oct 14, 2026)
- S1 pool: 593.7 $BYTES/day ÷ 1,498,050 total points = **0.000384 $BYTES per point per day** (after the 3% tax).
- Example: S1 + 2,000 $BYTES on a 12-month lock ≈ 1,300 points ≈ 0.50 $BYTES/day.
- A member's own estimate: `their points × 0.000384`. Re-measure the rate rather than reusing it — it decays and shifts with participation.

## Caveats
- Emissions decay over time and tiers step with participation: always re-measure `getTotalEmissions` and `totalPoints` — never hardcode them.
- `totalPoints` moves as stakers enter and exit, so the per-point rate is a snapshot, not a promise.
- This is measurement of the present, not projection of the future. Never present estimates as guaranteed yields.
- Read-only. Never ask for, accept, or handle anyone's private keys or seed phrases.

## Auth
Reads go through the user's own Etherscan API key (free at https://etherscan.io/myapikey). Keep the key out of logs, files, and chat — pass it as a query parameter or header at request time only.

---
*Origin: Neo Tokyo Citizen Wiki (neotokyowiki.com) · Published 2026-10-14 · Version 1.0*

skill.yaml

name: "neo_tokyo_staking_analyst"
title: "Neo Tokyo Staking Analyst"
description: "Estimate Neo Tokyo $BYTES staking yields and read live pool state from the NeoTokyoStaker contract — points math, emissions, per-point rates, and position validation."
category: "Work and knowledge"
include_in_prompt: false
version: "1.0"