colony-solana

# Colony Game Skill You are an autonomous agent managing a Colony game account on Solana mainnet. Colony is an idle game where you buy land plots that mine $OLO tokens. Your job is to maximize earnings through strategic land purchases, upgrades, and timely claim collection. ## Environment Setup ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `SOLANA_PRIVATE_KEY` | Yes | Base58-encoded Solana keypair secret key (auto-generated on first run) | | `SOLANA_RPC_URL` | No | Solana RPC endpoint (default: `https://api.mainnet-beta.solana.com`) | | `JUPITER_API_KEY` | For swaps/price | Free API key from https://portal.jup.ag (required for `swap`, `swap-quote`, `price` commands) | ### First-Time Onboarding Follow these steps **exactly in order** the first time you set up: #### Step 1: Install dependencies ```bash cd <skill-directory> npm install ``` #### Step 2: Generate your wallet If `SOLANA_PRIVATE_KEY` is not already set, generate a new wallet: ```bash node colony-cli.mjs generate-wallet ``` This outputs JSON with `publicKey` and `privateKey`. **Immediately**: 1. Save `privateKey` as your `SOLANA_PRIVATE_KEY` environment variable. **Never share it.** 2. Note the `publicKey` — this is the wallet address. #### Step 3: Tell your owner to fund the wallet Send a message to your owner with: - **Wallet address**: the `publicKey` from step 2 - **How much to send**: minimum **0.05 SOL** for transaction fees. For a full start (buying first land), recommend **0.5-1 SOL** so you can swap SOL for $OLO tokens. - **What it's for**: "This is my Colony game wallet. I need SOL to pay transaction fees and swap for $OLO tokens to buy land." #### Step 4: Wait for funding, then verify Once the owner confirms they sent SOL, check: ```bash node colony-cli.mjs status ``` Confirm `solBalance` > 0. If still 0, wait 30 seconds and check again. #### Step 5: Swap SOL for $OLO tokens You need $OLO tokens to buy land (10,000 $OLO per land). First get a quote: ```bash node colony-cli.mjs swap-quote --sol-amount 0.3 ``` If the output looks reasonable, execute the swap: ```bash node colony-cli.mjs swap --sol-amount 0.3 ``` #### Step 6: Buy your first land Find an available plot and buy it: ```bash node colony-cli.mjs find-land --count 1 node colony-cli.mjs buy-land --land-id <id-from-above> ``` #### Step 7: Verify and start autonomous loop ```bash node colony-cli.mjs status ``` You should now see 1 land mining $OLO. From here, follow the **Autonomous Loop** in the Strategy Guide section. ## Game Mechanics ### How Colony Works - Players buy **land plots** (IDs 1-21000) for **10,000 $OLO** each (tokens are burned) - Each land **mines $OLO tokens** continuously based on its level - Players **claim** accumulated earnings to receive real $OLO tokens from the vault - Lands can be **upgraded** (levels 1-10) to increase mining speed - Each wallet can own **up to 10 lands** - $OLO is a Token-2022 SPL token on Solana mainnet ### Earning Speeds (tokens/day by level) | Level | Earnings/Day | Cumulative Upgrade Cost | |-------|-------------|------------------------| | 1 | 1,000 | 10,000 (purchase) | | 2 | 2,000 | 11,000 | | 3 | 3,000 | 13,000 | | 4 | 5,000 | 17,000 | | 5 | 8,000 | 25,000 | | 6 | 13,000 | 41,000 | | 7 | 21,000 | 73,000 | | 8 | 34,000 | 137,000 | | 9 | 45,000 | 265,000 | | 10 | 79,000 | 417,000 | ### Upgrade Costs | Upgrade | Cost ($OLO) | Extra Earnings/Day | ROI (days) | |---------|-----------|-------------------|------------| | L1 -> L2 | 1,000 | +1,000 | 1.0 | | L2 -> L3 | 2,000 | +1,000 | 2.0 | | L3 -> L4 | 4,000 | +2,000 | 2.0 | | L4 -> L5 | 8,000 | +3,000 | 2.7 | | L5 -> L6 | 16,000 | +5,000 | 3.2 | | L6 -> L7 | 32,000 | +8,000 | 4.0 | | L7 -> L8 | 64,000 | +13,000 | 4.9 | | L8 -> L9 | 128,000 | +11,000 | 11.6 | | L9 -> L10 | 152,000 | +34,000 | 4.5 | | New L1 land | 10,000 | +1,000 | 10.0 | ## CLI Command Reference All commands output JSON. All write commands require `SOLANA_PRIVATE_KEY`. ### Setup Commands #### `generate-wallet` — Generate a new Solana keypair ```bash node colony-cli.mjs generate-wallet ``` Returns: `publicKey` (address to fund), `privateKey` (save as `SOLANA_PRIVATE_KEY`). No env vars needed. ### Read Commands (no private key needed for `game-state`, `land-info`, `price`) #### `game-state` — Global game state ```bash node colony-cli.mjs game-state ``` Returns: game active status, total lands sold, vault balances, addresses. #### `status` — Full wallet + game overview ```bash node colony-cli.mjs status ``` Returns: wallet SOL/OLO balances, owned lands with levels and pending earnings. #### `land-info` — Detailed land info with ROI analysis ```bash node colony-cli.mjs land-info --land-id 42 ``` Returns: land level, earnings rate, pending earnings, upgrade cost and ROI. #### `find-land` — Find available (unowned) land IDs ```bash node colony-cli.mjs find-land --count 3 ``` Returns: list of available land IDs (default: 5). #### `price` — Current $OLO token price ```bash node colony-cli.mjs price ``` Returns: USD price from Jupiter. #### `recommend` — AI-friendly strategic recommendation ```bash node colony-cli.mjs recommend ``` Returns: prioritized list of recommended actions with ROI analysis. ### Write Commands (require `SOLANA_PRIVATE_KEY`) #### `buy-land` — Buy a land plot ```bash node colony-cli.mjs buy-land --land-id 42 ``` Burns 10,000 $OLO. Returns: transaction signature. #### `upgrade-land` — Upgrade land to next level ```bash node colony-cli.mjs upgrade-land --land-id 42 ``` Burns tokens based on current level. Returns: new level, cost, signature. #### `claim` — Claim earnings from one land ```bash node colony-cli.mjs claim --land-id 42 ``` Transfers pending $OLO from vault to wallet. Returns: claimed amount, signature. #### `claim-all` — Claim earnings from all owned lands ```bash node colony-cli.mjs claim-all ``` Batches up to 10 claims per transaction. Returns: total claimed, signatures. #### `swap-quote` — Jupiter swap quote (SOL -> $OLO) ```bash node colony-cli.mjs swap-quote --sol-amount 0.1 ``` Returns: expected $OLO output, price impact, route. #### `swap` — Execute Jupiter swap (SOL -> $OLO) ```bash node colony-cli.mjs swap --sol-amount 0.1 ``` Swaps SOL for $OLO via Jupiter aggregator. Returns: amounts, signature. ## Strategy Guide ### Decision Algorithm When `recommend` is called, it evaluates actions in this priority: 1. **Claim first** — If pending earnings > 1,000 $OLO, claim immediately 2. **Upgrade by ROI** — Sort all affordable upgrades by ROI (days to pay back); execute the fastest payback first 3. **Buy new land** — If under 10 lands and can afford 10,000 $OLO 4. **Swap SOL** — If low on $OLO but have SOL reserves ### ROI Priority Order Best upgrades to prioritize (lowest ROI = fastest payback): 1. L1 -> L2 (1.0 days) 2. L2 -> L3 (2.0 days) 3. L3 -> L4 (2.0 days) 4. L4 -> L5 (2.7 days) 5. L5 -> L6 (3.2 days) 6. L6 -> L7 (4.0 days) 7. L9 -> L10 (4.5 days) 8. L7 -> L8 (4.9 days) 9. New L1 land (10.0 days) 10. L8 -> L9 (11.6 days) — **worst ROI, skip unless everything else is maxed** ### Autonomous Loop Run this cycle every 4-6 hours: ``` 1. node colony-cli.mjs status # Check current state 2. node colony-cli.mjs claim-all # Claim if earnings > 1000 3. node colony-cli.mjs recommend # Get next best action 4. Execute recommended action # Buy/upgrade/swap 5. Repeat step 3-4 until no actions ``` ### Safety Rules - **SOL reserve**: Always keep >= 0.01 SOL for transaction fees - **Swap caution**: Get a quote first (`swap-quote`) before executing swaps - **Large swaps**: Confirm with user before swapping > 1 SOL - **Price check**: Run `price` before swaps to verify token value - **Error recovery**: If a transaction fails, wait 30 seconds and retry once ## Error Handling ### Common Errors and Recovery | Error | Cause | Recovery | |-------|-------|---------| | `Insufficient $OLO` | Not enough tokens | Run `recommend` to check if swap is needed | | `Game is paused` | Admin paused game | Wait and retry later | | `Land is already owned` | Land taken | Use `find-land` to find available IDs | | `Max lands reached` | 10 land limit | Focus on upgrades instead | | `Max level reached` | Land at L10 | No more upgrades for this land | | `You don't own this land` | Wrong land ID | Run `status` to see owned lands | | `Transaction confirmation timeout` | Network congestion | Wait 60s and check `status` (tx may have succeeded) | | `Jupiter quote/swap failed` | DEX issue | Retry after 30s; try smaller amount | ### Checking Transaction Status If a transaction times out, check your `status` to see if it actually went through (balance/land changes reflect success). ## Key Addresses | Item | Address | |------|---------| | Program ID | `BCVGJ5YoKMftBrt5fgDYhtvY7HVBccFofFiGqJtoRjqE` | | Game Token ($OLO) | `2pXjxbdHnYWtH2gtDN495Ve1jm8bs1zoUL6XsUi3pump` | | Game State PDA | `6JFTxovd2WcSh9RTXKrjTsKAKBTDfsUM3FsLMXEe3eNZ` | | Token Vault PDA | `EgduLawRwk77jSdUhAmtcEyzrxvZXsyL8y8Ubj4dVnLA` |