Stacking Lottery Skill

• Pot Discovery — List all known pot contracts with their current value and lock status.
• Pot State — Query full on-chain state for a pot: value, participant count, lock status, config, pool config, and details.
• Join Pot — Contribute STX to a pot before it fills and starts stacking.
• Start Pot — Trigger a full pot to begin stacking through the platform contract.
• Claim Rewards — Claim sBTC rewards if your address was selected as the VRF winner.
• Cancel Pot — Cancel a pot before it starts and recover contributed STX.

bun run wallet/wallet.ts unlock

Usage

bun run stacking-lottery/stacking-lottery.ts <subcommand> [options]

Subcommands

list-pots

bun run stacking-lottery/stacking-lottery.ts list-pots

{
  "network": "mainnet",
  "potCount": 3,
  "pots": [
    {
      "name": "Genesis",
      "contract": "SPT4SQP5RC1BFAJEQKBHZMXQ8NQ7G118F335BD85.Genesis",
      "maxParticipants": 2,
      "minAmountStx": 20,
      "currentValueUstx": "40000000",
      "isLocked": false
    }
  ]
}

get-pot-state

bun run stacking-lottery/stacking-lottery.ts get-pot-state --contract-name <name>

• --contract-name

  (required) — Pot contract name or full identifier (e.g.,

  SPT4SQP5RC1BFAJEQKBHZMXQ8NQ7G118F335BD85.STXLFG

  or

  STXLFG

  )

join-pot

bun run stacking-lottery/stacking-lottery.ts join-pot --contract-name <name> --amount <microStx>

• --contract-name

  (required) — Pot contract name (e.g.,

  STXLFG

  )

• --amount

  (required) — Amount to contribute in micro-STX (1 STX = 1,000,000 micro-STX)

start-pot

bun run stacking-lottery/stacking-lottery.ts start-pot --contract-name <name>

• --contract-name

  (required) — Pot contract name to start stacking

claim-rewards

bun run stacking-lottery/stacking-lottery.ts claim-rewards --contract-name <name>

• --contract-name

  (required) — Pot contract name to claim rewards from

cancel-pot

bun run stacking-lottery/stacking-lottery.ts cancel-pot --contract-name <name>

• --contract-name

  (required) — Pot contract name to cancel

Notes

• All stacking lottery operations are mainnet-only. Calls on testnet will return an error.
• Write operations require an unlocked wallet (use

  bun run wallet/wallet.ts unlock

  first).
• STX lock-up: When you join a pot, your STX is locked for one full PoX stacking cycle (~2 weeks). Do not join a pot with STX you need access to in the short term.
• VRF winner selection: One participant is chosen randomly at unlock. The winner receives all stacking yield in sBTC. All participants (including the winner) receive their original STX back.
• Timing windows: Pots can only be started during the prepare phase of a PoX cycle. If start-pot fails, check the current PoX cycle phase using

  bun run stacking/stacking.ts get-pox-info

  .
• Contract architecture: Individual pot contracts are deployed by

  SPT4SQP5RC1BFAJEQKBHZMXQ8NQ7G118F335BD85

  . The platform contract

  SP7FSE31MWSJJFTQBEQ1TT6TF3G4J6GDKE81SWD9.stackspots

  orchestrates starting pots and distributing rewards.
• Known pots: Genesis (max 2 participants, min 20 STX), BuildOnBitcoin (max 10, min 100 STX), STXLFG (max 100, min 21 STX).