feat(tokens/hackathon): add Squads-multisig hackathon prize program

A new Anchor 1.0 example: a hackathon prize program whose authority is an
external Squads multisig vault PDA. The onchain program is multisig-agnostic
- it stores an opaque `authority` pubkey and checks `signer == authority` on
each privileged handler. Squads handles propose/vote/execute off-program.

Instruction handlers:
- create_hackathon: open a hackathon under `authority`
- add_prize: register a prize with its own mint and vault ATA
- set_winner: record the winning pubkey for a prize (multisig)
- pay_winner: transfer exactly `prize.amount` to the recorded winner.
  Unpermissioned: anyone can call once the winner is set and the vault is
  funded.
- cancel_prize: drain the vault back to a refund target and lock the prize
  (multisig)
- close_hackathon: refund Hackathon rent once every prize is paid or
  cancelled (multisig)

Uses the SPL Token Interface throughout so the same compiled program works
for both classic SPL Token and Token-2022 mints. Per-prize mint and per-prize
vault PDA so one hackathon can mix denominations and surface a clean
PDA-derivation pattern.

This commit is program code + smoke build only; LiteSVM tests with a real
Squads 2-of-3 (Alice/Bob/Carol) committee follow in the next commit.

Author: Edward (Edwardbot)

tokens/hackathon/anchor/.gitignore

@@ -0,0 +1,7 @@
+.anchor
+.DS_Store
+target
+**/*.rs.bk
+node_modules
+test-ledger
+.yarn

tokens/hackathon/anchor/Anchor.toml

@@ -0,0 +1,16 @@
+[toolchain]
+solana_version = "3.1.8"
+
+[features]
+resolution = true
+skip-lint = false
+
+[programs.localnet]
+hackathon = "71AxoNytgqQrSFMvGREPeJ1E2btEoTMw8J4FALsmNcGx"
+
+[provider]
+cluster = "Localnet"
+wallet = "~/.config/solana/id.json"
+
+[scripts]
+test = "cargo test"

tokens/hackathon/anchor/Cargo.toml

@@ -0,0 +1,15 @@
+[workspace]
+members = [
+    "programs/*"
+]
+resolver = "2"
+
+[profile.release]
+overflow-checks = true
+lto = "fat"
+codegen-units = 1
+
+[profile.release.build-override]
+opt-level = 3
+incremental = false
+codegen-units = 1

tokens/hackathon/anchor/programs/hackathon/Cargo.toml

@@ -0,0 +1,35 @@
+[package]
+name = "hackathon"
+version = "0.1.0"
+description = "Created with Anchor"
+edition = "2021"
+
+[lib]
+crate-type = ["cdylib", "lib"]
+name = "hackathon"
+
+[features]
+default = []
+cpi = ["no-entrypoint"]
+no-entrypoint = []
+no-idl = []
+no-log-ix-name = []
+idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build"]
+anchor-debug = []
+custom-heap = []
+custom-panic = []
+
+[dependencies]
+anchor-lang = "1.0.0"
+anchor-spl = "1.0.0"
+sha2 = { version = "0.10", default-features = false }
+
+[dev-dependencies]
+litesvm = "0.11.0"
+solana-signer = "3.0.0"
+solana-keypair = "3.0.1"
+solana-kite = "0.3.0"
+borsh = "1.6.1"
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(target_os, values("solana"))'] }

tokens/hackathon/anchor/programs/hackathon/Xargo.toml

@@ -0,0 +1,2 @@
+[target.bpfel-unknown-unknown.dependencies.std]
+features = []

tokens/hackathon/anchor/programs/hackathon/src/error.rs

@@ -0,0 +1,23 @@
+use anchor_lang::prelude::*;
+
+#[error_code]
+pub enum HackathonError {
+    #[msg("Hackathon name must not be empty")]
+    EmptyName,
+    #[msg("Hackathon name exceeds the maximum length")]
+    NameTooLong,
+    #[msg("Prize has already been paid")]
+    AlreadyPaid,
+    #[msg("Prize has been cancelled")]
+    Cancelled,
+    #[msg("Prize has no winner set")]
+    NoWinner,
+    #[msg("Recorded winner does not match the supplied winner token account owner")]
+    WinnerMismatch,
+    #[msg("Vault balance is less than the prize amount")]
+    Underfunded,
+    #[msg("Prize counter overflow: this hackathon already holds the maximum prizes")]
+    PrizeCounterOverflow,
+    #[msg("Cannot close hackathon: at least one prize is still active")]
+    PrizesStillActive,
+}

tokens/hackathon/anchor/programs/hackathon/src/instructions/add_prize.rs

@@ -0,0 +1,79 @@
+use anchor_lang::prelude::*;
+use anchor_spl::{
+    associated_token::AssociatedToken,
+    token_interface::{Mint, TokenAccount, TokenInterface},
+};
+
+use crate::error::HackathonError;
+use crate::state::{Hackathon, Prize};
+
+#[derive(Accounts)]
+pub struct AddPrize<'info> {
+    // Rent payer. Separate from `authority` to allow a non-signing Squads
+    // vault PDA to be the authority while a human keypair funds the call.
+    #[account(mut)]
+    pub payer: Signer<'info>,
+
+    // Hackathon admin. Must match `hackathon.authority`.
+    pub authority: Signer<'info>,
+
+    #[account(
+        mut,
+        has_one = authority,
+        seeds = [b"hackathon", authority.key().as_ref(), super::name_seed(&hackathon.name).as_ref()],
+        bump = hackathon.bump,
+    )]
+    pub hackathon: Account<'info, Hackathon>,
+
+    // Per-prize mint. Using the token interface so the same compiled program
+    // works for classic SPL Token (e.g. USDC) and Token-2022 mints.
+    #[account(mint::token_program = token_program)]
+    pub mint: InterfaceAccount<'info, Mint>,
+
+    #[account(
+        init,
+        payer = payer,
+        space = Prize::DISCRIMINATOR.len() + Prize::INIT_SPACE,
+        seeds = [b"prize", hackathon.key().as_ref(), &[hackathon.prize_count]],
+        bump
+    )]
+    pub prize: Account<'info, Prize>,
+
+    // Vault ATA for this prize. Owned by the Prize PDA so `pay_winner` can
+    // sign the outgoing transfer with the prize's seeds.
+    #[account(
+        init,
+        payer = payer,
+        associated_token::mint = mint,
+        associated_token::authority = prize,
+        associated_token::token_program = token_program,
+    )]
+    pub vault: InterfaceAccount<'info, TokenAccount>,
+
+    pub associated_token_program: Program<'info, AssociatedToken>,
+    pub token_program: Interface<'info, TokenInterface>,
+    pub system_program: Program<'info, System>,
+}
+
+pub fn handle_add_prize(context: Context<AddPrize>, amount: u64) -> Result<()> {
+    let hackathon = &mut context.accounts.hackathon;
+    let index = hackathon.prize_count;
+
+    context.accounts.prize.set_inner(Prize {
+        hackathon: hackathon.key(),
+        index,
+        mint: context.accounts.mint.key(),
+        amount,
+        winner: None,
+        paid: false,
+        cancelled: false,
+        bump: context.bumps.prize,
+    });
+
+    hackathon.prize_count = hackathon
+        .prize_count
+        .checked_add(1)
+        .ok_or(HackathonError::PrizeCounterOverflow)?;
+
+    Ok(())
+}

tokens/hackathon/anchor/programs/hackathon/src/instructions/cancel_prize.rs

@@ -0,0 +1,118 @@
+use anchor_lang::prelude::*;
+use anchor_spl::token_interface::{
+    close_account, transfer_checked, CloseAccount, Mint, TokenAccount, TokenInterface,
+    TransferChecked,
+};
+
+use crate::error::HackathonError;
+use crate::state::{Hackathon, Prize};
+
+// Cancel an unpaid prize: drain the vault to `refund_token_account`, close
+// the vault, and lock the prize so `pay_winner` can no longer run. Useful
+// when a prize is funded but never claimed, or when the committee wants to
+// reclaim surplus tokens left in a vault after `pay_winner` paid the exact
+// `prize.amount`.
+#[derive(Accounts)]
+#[instruction(prize_index: u8)]
+pub struct CancelPrize<'info> {
+    // Hackathon admin. Must match `hackathon.authority`.
+    pub authority: Signer<'info>,
+
+    // Where the vault's reclaimed rent lamports go. Separate from `authority`
+    // so a Squads vault PDA (which cannot directly receive non-account
+    // lamports in this context) can still authorise the cancellation while a
+    // human keypair takes the rent refund.
+    #[account(mut)]
+    pub rent_destination: SystemAccount<'info>,
+
+    #[account(
+        has_one = authority,
+        seeds = [b"hackathon", authority.key().as_ref(), super::name_seed(&hackathon.name).as_ref()],
+        bump = hackathon.bump,
+    )]
+    pub hackathon: Account<'info, Hackathon>,
+
+    #[account(
+        mut,
+        seeds = [b"prize", hackathon.key().as_ref(), &[prize_index]],
+        bump = prize.bump,
+        has_one = mint,
+        constraint = prize.hackathon == hackathon.key(),
+    )]
+    pub prize: Account<'info, Prize>,
+
+    pub mint: InterfaceAccount<'info, Mint>,
+
+    #[account(
+        mut,
+        associated_token::mint = mint,
+        associated_token::authority = prize,
+        associated_token::token_program = token_program,
+    )]
+    pub vault: InterfaceAccount<'info, TokenAccount>,
+
+    // Token account that receives any tokens currently held in the vault.
+    // Must match `mint` but otherwise unconstrained — the committee picks
+    // where to send the refund.
+    #[account(
+        mut,
+        token::mint = mint,
+        token::token_program = token_program,
+    )]
+    pub refund_token_account: InterfaceAccount<'info, TokenAccount>,
+
+    pub token_program: Interface<'info, TokenInterface>,
+}
+
+pub fn handle_cancel_prize(context: Context<CancelPrize>, _prize_index: u8) -> Result<()> {
+    let prize = &mut context.accounts.prize;
+    require!(!prize.paid, HackathonError::AlreadyPaid);
+    require!(!prize.cancelled, HackathonError::Cancelled);
+
+    let hackathon_key = context.accounts.hackathon.key();
+    let prize_index_byte = [prize.index];
+    let bump = [prize.bump];
+    let seeds = &[
+        b"prize".as_ref(),
+        hackathon_key.as_ref(),
+        prize_index_byte.as_ref(),
+        bump.as_ref(),
+    ];
+    let signer_seeds = [&seeds[..]];
+
+    // Drain whatever is in the vault back to the refund target. This may be
+    // zero (vault never funded) or more than `prize.amount` (vault was
+    // over-funded); either is fine.
+    let vault_amount = context.accounts.vault.amount;
+    if vault_amount > 0 {
+        let transfer_accounts = TransferChecked {
+            from: context.accounts.vault.to_account_info(),
+            mint: context.accounts.mint.to_account_info(),
+            to: context.accounts.refund_token_account.to_account_info(),
+            authority: prize.to_account_info(),
+        };
+        let cpi_context = CpiContext::new_with_signer(
+            context.accounts.token_program.key(),
+            transfer_accounts,
+            &signer_seeds,
+        );
+        transfer_checked(cpi_context, vault_amount, context.accounts.mint.decimals)?;
+    }
+
+    // Close the vault so its rent comes back. Prize account itself stays
+    // open: it's an immutable record that this prize was cancelled.
+    let close_accounts = CloseAccount {
+        account: context.accounts.vault.to_account_info(),
+        destination: context.accounts.rent_destination.to_account_info(),
+        authority: prize.to_account_info(),
+    };
+    let cpi_context = CpiContext::new_with_signer(
+        context.accounts.token_program.key(),
+        close_accounts,
+        &signer_seeds,
+    );
+    close_account(cpi_context)?;
+
+    prize.cancelled = true;
+    Ok(())
+}

tokens/hackathon/anchor/programs/hackathon/src/instructions/close_hackathon.rs

@@ -0,0 +1,56 @@
+use anchor_lang::prelude::*;
+
+use crate::error::HackathonError;
+use crate::state::Hackathon;
+
+// Close the Hackathon account and refund its rent to `rent_destination`.
+// Permitted only once every registered Prize is either paid or cancelled —
+// the handler reads each Prize account from `remaining_accounts` and checks
+// its state. This avoids storing a separate `active_prize_count` field that
+// could drift out of sync with the per-Prize flags.
+#[derive(Accounts)]
+pub struct CloseHackathon<'info> {
+    pub authority: Signer<'info>,
+
+    #[account(mut)]
+    pub rent_destination: SystemAccount<'info>,
+
+    #[account(
+        mut,
+        has_one = authority,
+        close = rent_destination,
+        seeds = [b"hackathon", authority.key().as_ref(), super::name_seed(&hackathon.name).as_ref()],
+        bump = hackathon.bump,
+    )]
+    pub hackathon: Account<'info, Hackathon>,
+}
+
+pub fn handle_close_hackathon(context: Context<CloseHackathon>) -> Result<()> {
+    let hackathon = &context.accounts.hackathon;
+
+    // Caller must pass every Prize account for this hackathon as remaining
+    // accounts (in index order). Each one must either be paid or cancelled.
+    require!(
+        context.remaining_accounts.len() == hackathon.prize_count as usize,
+        HackathonError::PrizesStillActive
+    );
+
+    for (expected_index, prize_account_info) in context.remaining_accounts.iter().enumerate() {
+        let prize = Account::<crate::state::Prize>::try_from(prize_account_info)?;
+        require_keys_eq!(
+            prize.hackathon,
+            hackathon.key(),
+            HackathonError::PrizesStillActive
+        );
+        require!(
+            prize.index == expected_index as u8,
+            HackathonError::PrizesStillActive
+        );
+        require!(
+            prize.paid || prize.cancelled,
+            HackathonError::PrizesStillActive
+        );
+    }
+
+    Ok(())
+}