Solana Token Leaderboard with Twitter Login releases

A WordPress plugin that lets users log in with their X (Twitter) account, link a Solana wallet, and appear on a ranked token balance leaderboard. Includes a treasury-powered auto-payout system that distributes native SOL to token holders on a configurable schedule, plus a live countdown widget for the front end.

Features

• Twitter / X OAuth 2.0 login — PKCE + confidential client; no passwords stored
• Solana wallet linking — users paste their wallet address after logging in
• Daily balance sync — WP-Cron fetches each user's SPL token balance once per day; can also be triggered manually from the admin panel
• Daily profile refresh — avatars, display names, and handles are re-fetched alongside the balance check so leaderboard photos stay current
• Leaderboard shortcode — ranked table with medals, avatars, Solscan wallet links, customizable color scheme
• Auto-payout system — scheduled SOL distribution to token holders on a configurable interval with dust filtering, min-holder threshold, reserve protection, and payout history
• Payout countdown widget — live front-end banner showing next payout countdown, SOL prize pool, total distributed, and qualified holder count
• Five shortcodes — login button, wallet form, token balance card, leaderboard, payout countdown

Requirements

Requirement	Minimum
WordPress	5.8
PHP	7.4 (64-bit)
PHP extensions	sodium, openssl, bcmath or gmp (auto-payout signing)
Twitter Developer App	OAuth 2.0, confidential client, tweet.read users.read offline.access scopes

Installation

1. Upload the solana-twitter-login folder to wp-content/plugins/
2. Activate the plugin in Plugins → Installed Plugins
3. Go to Settings → Solana Twitter Login and fill in your credentials

Twitter / X App Setup

1. Create an app at developer.twitter.com
2. Enable OAuth 2.0 — set the client type to Confidential client
3. Add the callback URL shown on the settings page: https://yoursite.com/?stl_action=twitter_callback
4. Enable scopes: tweet.read, users.read, offline.access
5. Copy the Client ID and Client Secret into the plugin settings

Shortcodes

[stl_login_button]

A Login with X button for guests. Once connected, shows the user's avatar, display name, handle, and a Disconnect button.

[stl_wallet_form]

A form for logged-in users to link, change, or remove their Solana wallet. Fetches the token balance immediately on save.

[stl_token_balance]

A card showing the current user's token balance and last-updated time. Hidden for guests and users without a wallet.

[stl_leaderboard]

A ranked table of all users sorted by token balance.

Attribute	Default	Description
limit	25	Max rows shown (max 200)
show_wallet	yes	Show truncated wallet address linked to Solscan
show_updated	yes	Show "last updated" time per row
highlight	yes	Highlight the logged-in user's row with a "You" badge

[stl_payout_countdown]

A live countdown banner showing the next auto-payout time, SOL prize pool balance, total SOL distributed all-time, and qualified holder count. Updates every second (countdown) and polls the server every 30 seconds for fresh stats.

Attribute	Default	Description
show_stats	yes	Show the three stat cards below the banner

Example layouts:

[stl_login_button]
[stl_wallet_form]
[stl_token_balance]

[stl_leaderboard limit="10" show_wallet="no"]

[stl_payout_countdown]

Treasury Wallet Setup

1. Export your treasury wallet's 64-byte Base58 keypair from Phantom or Solflare
2. Paste it into the Private Key field in Settings → Solana Twitter Login and save — the key is encrypted with AES-256-GCM before being written to the database (key derived from WordPress's AUTH_KEY + AUTH_SALT)
3. Verify the derived Public Key displayed matches your wallet address

Use a dedicated treasury wallet — never your main wallet.

Auto-Payout System

The auto-payout system distributes native SOL from the treasury wallet to token holders on a configurable WP-Cron schedule.

How it works

1. Optionally claims pump.fun creator fees into the treasury wallet on a separate interval
2. Reads the treasury balance and subtracts the configured reserve
3. Checks the qualified holder count — if below the minimum threshold, the cycle is skipped and the countdown pauses
4. Builds a recipient list pro-rata by token balance (or rank), filtering out any holder whose share falls below the dust threshold
5. Distributes SOL to all qualifying recipients in a single pass
6. Records the result — payout history (last 20 cycles) is visible in the admin with per-recipient amounts and Solscan transaction links

Qualification

A holder qualifies for the recipient list when they have:

• A linked Solana wallet
• A positive token balance
• A pro-rata SOL share that meets or exceeds the Minimum payout per holder setting

The "Qualified Holders" count on the countdown widget reflects exactly how many holders would receive SOL if a payout ran right now (dust filter applied against the current pool balance). The sub-text shows the minimum token balance required to clear that threshold.

Settings

Setting	Description
Enable auto-payouts	Master on/off switch
Payout interval (days)	How often a payout cycle runs
Distribution method	Proportional to token balance, or by leaderboard rank
Maximum SOL per cycle	Cap the total distributed each cycle (0 = no cap)
Activate payout when at least N holders	Minimum qualified holders required before payouts fire
Auto-claim pump.fun fees	Sweep accumulated creator fees into the treasury before each payout
Claim fees every N days	How often to call the fee-claim instruction
Reserve SOL	Minimum SOL kept on the treasury to cover transaction fees
Minimum payout per holder	Skip holders whose pro-rata share falls below this amount

Manual trigger

The admin panel includes a Trigger Payout Now button that runs the full payout cycle immediately, bypassing the schedule (but still enforcing all other settings).

Payout Countdown Widget

Add [stl_payout_countdown] to any page. The banner shows:

• LIVE — a pulsing badge (color customizable)
• Next payout countdown — live timer; shows "waiting for N more holders" if below the min-holder threshold, or "disabled" if auto-payouts are turned off
• Every N day(s) — the configured interval
• Last paid — relative time since the last successful payout
• SOL Prize Pool — current treasury balance (refreshes every 30 s)
• Total SOL Distributed — all-time cumulative payout amount
• Qualified Holders — holders who would receive SOL if a payout ran now, plus the minimum token balance required to qualify

Settings Reference

Setting	Description
Twitter Client ID	OAuth 2.0 client ID from the developer portal
Twitter Client Secret	Encrypted at rest — paste to set, leave blank to keep existing
Token Mint Address	SPL token mint (defaults to the plugin constant)
Solana RPC Endpoint	Mainnet RPC URL (default is public; use Helius/QuickNode for production)
After Login Redirect URL	Where to send users after a successful Twitter login
Leaderboard Colors	Color pickers for gradient, accent, rank highlight, "You" row background, payout banner background, and LIVE badge
Treasury Private Key	Encrypted 64-byte Base58 keypair for the auto-payout treasury wallet

Security

• OAuth tokens encrypted at rest — Twitter access and refresh tokens are stored encrypted (AES-256-GCM) in the database, not as plaintext
• Client secret encrypted at rest — stored the same way as the treasury key; never echoed back to the page
• OAuth state IP binding — the OAuth state token is HMAC-bound to the initiating IP address, preventing session fixation and CSRF
• Rate limiting — OAuth callback is limited to 10 attempts per IP per 5 minutes
• Strict wallet validation — addresses are base58-decoded and verified to produce exactly 32 bytes before acceptance
• No raw SQL — all data access goes through the WordPress meta API
• Key zeroing — decrypted private keys are wiped from memory with sodium_memzero() immediately after use

Changelog

3.0.1

• Add estimated next payout to the [stl_token_balance] card — shows each holder's pro-rata SOL share based on current pool balance
• Non-qualifying wallets show "needs N more tokens to qualify" inline instead of a payout estimate
• Dust filter applied to estimate — card only shows a payout amount if the holder's share clears the minimum payout threshold

3.0.0

• Add auto-payout system: scheduled SOL distribution from treasury wallet on a configurable WP-Cron interval
• Add [stl_payout_countdown] shortcode: live countdown banner with SOL prize pool, total distributed, and qualified holder stats
• Qualified holder count simulates the dust filter against the current pool balance — shows exactly how many holders would receive SOL now
• Holder stat card shows the minimum token balance required to clear the dust threshold
• Countdown banner shows distinct states: live timer, "waiting for N more holders", or "disabled"
• Add payout history table in admin (last 20 cycles) with per-recipient amounts and Solscan transaction links
• Add Manual Payout trigger button in admin
• Add Auto-claim pump.fun creator fees option with configurable interval
• Add distribution method setting: proportional by token balance or by leaderboard rank
• Add minimum holder threshold: payouts skip until enough qualified holders exist
• Add reserve SOL setting: keeps a minimum balance on treasury for transaction fees
• Add maximum SOL per cycle cap
• Add dust filter: skip holders whose pro-rata share is below the minimum payout threshold
• Add treasury balance display inline in admin settings with one-click refresh
• RPC calls now retry up to 3 times with backoff on network errors or HTTP 429
• Add color picker for payout banner background and LIVE badge
• Daily cron now refreshes treasury balance and busts all holder count caches after balance updates
• Fix: auto-payout min-holder threshold was not enforced inside the payout run (payouts could fire with fewer holders than configured)
• Fix: checkbox settings (enable auto-payouts, claim fees) could not be unchecked due to missing hidden field pattern

2.1.3

• Security: encrypt OAuth access/refresh tokens in wp_usermeta (AES-256-GCM)
• Security: encrypt Twitter client secret at rest; settings form uses placeholder instead of echoing value
• Security: airdrop execute loads recipients from server-side transient, not client-submitted JSON
• Security: OAuth state token is HMAC-bound to client IP to prevent CSRF/session fixation
• Security: rate limit OAuth callback to 10 requests per IP per 5 minutes
• Security: wallet validation now base58-decodes and checks for 32 bytes
• Security: generic user-facing error messages; detailed errors logged server-side only
• Security: cap OAuth callback retry sleep to 1s (was up to 15s) to prevent PHP worker exhaustion

2.1.2

• Fix: Twitter avatars and profile data now refresh during the daily balance check cron so leaderboard photos stay current without users needing to reconnect

2.0.0 – 2.1.1

• Treasury wallet import with AES-256-GCM encryption
• SOL distribution signed with libsodium Ed25519
• Two distribution methods: proportional by balance, or by leaderboard rank

1.0.0

• Initial release: Twitter/X OAuth login, Solana wallet linking, daily balance sync, leaderboard shortcode with color customization