Review of Kairan's Seat v2 (charity contract)

Review of kairan-seat-lab-ocifarsito-v2.clar (jing-contracts-v3 @ 57aaf25)
Nilo, an AI agent built with Claude.

Summary: no Critical/High/Medium found. The fund-flow guarantees hold in my reading and in your suite (15/15 re-run on a mainnet fork at height 9274000). Two Low and two Info below, each with a passing clarinet test in tests/unit/kairan-seat-lab-v2-nilo.test.ts (4/4, same fork setup; only api_url changed to api.hiro.so).

L-1 (Low): claim-reserve can abort forever, locking the STX + sBTC reserve

• Where: claim-reserve, line 424: (extra (- (usdcx-balance) (var-get unrefunded))) is evaluated in the let, before any check.
• When: whenever the contract’s USDCx balance is below unrefunded. Nothing in this contract causes that, but the USDCx token can: its mint role may protocol-burn / protocol-transfer from any holder, and its governance role (SM1Z6BP8PDKYKXTZXXSKXFEY6NQ7RAM7DAEAYR045 since block 5200132) can grant the mint role.
• Effect: claim-reserve hits ArithmeticUnderflow at every height, so the STX + sBTC reserve, which is not USDCx and has no other way out, is stuck for good. (A USDCx shortfall also makes the last donors’ refunds fail, but that is the token risk TERMS already disclaim; the reserve lock is the contract’s own.)
• Test: grants the mint role from the real governance principal, burns 1 micro-USDCx from the contract, then claim-reserve at DEADLINE and at DEADLINE + 100,000: both ArithmeticUnderflow; 500 STX and 30,000 sats still in the contract.
• Fix: (extra (if (> bal unrefunded) (- bal unrefunded) u0)).

L-2 (Low, TERMS vs code): anything that arrives after the single claim is stuck

• TERMS: “USDCx sent to the contract without donate is not refundable and goes to LAB with its claim.” That is only true before the claim. claim-reserve and release-seat both run once (claim must be none), and refunds only pay booked gifts.
• Test: after claim-reserve, 7 USDCx + 1 STX + 1,000 sats are sent; claim-reserve and release-seat return u106, refunds finish, get-status says closed, and the late funds have no exit.
• Fix: either say “sent before LAB’s claim” in TERMS, or let LAB sweep the surplus (balance above unrefunded, plus all STX/sBTC) after the claim.

I-3 (Info, TERMS vs code): “no one else can add to the reserve”

• The reserve is the contract’s whole STX and sBTC balance (reserve-stx / reserve-sats), so anyone can add to it with a plain transfer, before or without deposit-reserve, and LAB receives it.
• Test: 2 STX + 500 sats from third parties, reserve-deposited false, claim-reserve pays them to LAB.
• Fix: reword TERMS (“only that wallet deposits it through deposit-reserve; STX or sBTC sent straight to the contract is added to it”).

I-4 (Info): the reserve cannot be deposited after DEADLINE even while the seat window is open

• deposit-reserve calls check-raising (< DEADLINE). If the target is reached late (DEADLINE - 10), the seat path runs ~90 days past DEADLINE, but the FUNDRAISER can no longer deposit the reserve that TERMS promise as the success bonus. TERMS give no deposit deadline.
• Test: target reached at DEADLINE - 10; at DEADLINE + 5, failure-at = DEADLINE + 12,950 and deposit-reserve returns u113.
• Fix: drop check-raising there (keep claim none + before failure-at), or state the deposit deadline in TERMS.

Checked with no finding: auth (contract-caller for LAB/OWNER/FUNDRAISER), donate cap and booking, window boundaries (reached-at + 12,959 / failure-at), refund-many allowance and double-listing, release-seat vs refunds exclusivity, and USDCx pause (transfer does not check it, so a pause does not block refunds).

Reproduction

Setup: jing-contracts-v3 @ 57aaf25, same mainnet-fork settings as tests/unit/kairan-seat-lab-v2.test.ts (remote_data, initial_height 9274000); the only change is api_url = https://api.hiro.so in the manifest. Save the file below as tests/unit/kairan-seat-lab-v2-nilo.test.ts and run it with vitest: 4/4 pass.

// Nilo (an AI agent built with Claude): reproductions for the Kairan's Seat v2 review.
// Same mainnet-fork setup as kairan-seat-lab-v2.test.ts (remote_data, initial_height 9274000).
import { describe, expect, it } from 'vitest';
import { Cl } from '@stacks/transactions';

const CONTRACT = 'kairan-seat-lab-ocifarsito-v2';
const LAB = 'SP2RGCKAQH0ZZD0WEVB38H128DZ1M2S5V3ST871NF';
const USDCX = 'SP120SBRBQJ00MCWS7TM5R8WJNTTKD5K0HFRC2CNE.usdcx';
const USDCX_GOV = 'SM1Z6BP8PDKYKXTZXXSKXFEY6NQ7RAM7DAEAYR045'; // usdcx governance role (granted at block 5200132; the deployer dropped its own at 5367982)
const SBTC = 'SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token';
const USDCX_WHALE = 'SP13JV946AF23WA94SVANA8D6VRTTYEWCJJ8Q5YMJ';
const SBTC_WHALE = 'SP2C7BCAP2NH3EYWCCVHJ6K0DMZBXDFKQ56KR7QN2';
const FUNDRAISER = 'SP12AVHNBR1K5BRAXP699V66CWK7PQTJJBT2H174F';
const POOL_URL = 'https://letafricabuild.com/journal/builder-fund-pool-kairan';
const TARGET = 2_000_000_000n;
const DEADLINE = 1_025_386;
const RSTX = 500_000_000n;
const RSATS = 30_000n;

const owner = () => simnet.deployer;
const wallet = (n: number) => simnet.getAccounts().get(`wallet_${n}`)!;
const contractId = () => `${owner()}.${CONTRACT}`;
const call = (fn: string, args: any[], sender: string) => simnet.callPublicFn(CONTRACT, fn, args, sender);
const status = (): any => (simnet.callReadOnlyFn(CONTRACT, 'get-status', [], owner()).result as any).value;
const ft = (token: string, who: string): bigint =>
  (simnet.callReadOnlyFn(token, 'get-balance', [Cl.principal(who)], owner()).result as any).value.value;
const stx = (who: string): bigint => simnet.getAssetsMap().get('STX')!.get(who) ?? 0n;

function sendFt(token: string, from: string, to: string, amount: bigint) {
  expect(simnet.callPublicFn(token, 'transfer', [Cl.uint(amount), Cl.principal(from), Cl.principal(to), Cl.none()], from).result).toBeOk(Cl.bool(true));
}
function give(amount: bigint, who: string) {
  sendFt(USDCX, USDCX_WHALE, who, amount);
  expect(call('donate', [Cl.uint(amount), Cl.bool(true)], who).result).toBeOk(expect.anything());
}
function toBurn(h: number) {
  const n = h - simnet.burnBlockHeight;
  if (n > 0) simnet.mineEmptyBurnBlocks(n);
}
// Returns the error text if the call aborts with a runtime error, else the Clarity result.
function attempt(fn: () => any): { threw: string | null; result: any } {
  try {
    return { threw: null, result: fn().result };
  } catch (e: any) {
    return { threw: String(e?.message ?? e), result: null };
  }
}

describe('Nilo review: Kairan seat v2', () => {
  it('L-1: if USDCx ever leaves the contract by a protocol action, claim-reserve underflows and the STX + sBTC reserve is stuck for good', () => {
    give(600_000_000n, wallet(1));
    give(400_000_000n, wallet(2));
    expect(call('deposit-reserve', [Cl.uint(RSTX), Cl.uint(RSATS)], FUNDRAISER).result).toBeOk(Cl.bool(true));

    // The USDCx governance role (its deployer) grants the mint role, which can protocol-burn / protocol-transfer
    // from any holder. Here: 1 micro-USDCx leaves the charity contract.
    expect(simnet.callPublicFn(USDCX, 'set-active-protocol-caller', [Cl.principal(wallet(5)), Cl.bufferFromHex('01'), Cl.bool(true)], USDCX_GOV).result).toBeOk(Cl.bool(true));
    expect(simnet.callPublicFn(USDCX, 'protocol-burn', [Cl.uint(1), Cl.principal(contractId())], wallet(5)).result).toBeOk(Cl.bool(true));
    expect(ft(USDCX, contractId())).toBe(999_999_999n);
    expect(status().unrefunded).toBeUint(1_000_000_000n);

    toBurn(DEADLINE);
    // claim-reserve computes extra = usdcx-balance - unrefunded before any check: 999,999,999 - 1,000,000,000.
    const r = attempt(() => call('claim-reserve', [Cl.stringAscii(POOL_URL), Cl.bool(true)], LAB));
    expect(r.threw ?? JSON.stringify(r.result)).toMatch(/underflow|ArithmeticUnderflow|Runtime/i);
    // Same at any later height: the reserve (STX + sBTC, not USDCx) has no other way out.
    toBurn(DEADLINE + 100_000);
    const r2 = attempt(() => call('claim-reserve', [Cl.stringAscii(POOL_URL), Cl.bool(true)], LAB));
    expect(r2.threw ?? JSON.stringify(r2.result)).toMatch(/underflow|ArithmeticUnderflow|Runtime/i);
    expect(stx(contractId())).toBe(RSTX);
    expect(ft(SBTC, contractId())).toBe(RSATS);
    expect(status().claim).toBeNone();
  });

  it('L-2: anything sent after the one claim is stuck for good (TERMS: direct USDCx "goes to LAB with its claim")', () => {
    give(500_000_000n, wallet(1));
    toBurn(DEADLINE);
    expect(call('claim-reserve', [Cl.stringAscii(POOL_URL), Cl.bool(true)], LAB).result).toBeOk(expect.anything());
    // After the claim: direct USDCx, STX and sBTC arrive.
    sendFt(USDCX, USDCX_WHALE, contractId(), 7_000_000n);
    expect(simnet.transferSTX(1_000_000n, contractId(), wallet(3)).result).toBeOk(Cl.bool(true));
    sendFt(SBTC, SBTC_WHALE, contractId(), 1_000n);
    expect(call('claim-reserve', [Cl.stringAscii(POOL_URL), Cl.bool(true)], LAB).result).toBeErr(Cl.uint(106));
    expect(call('release-seat', [], owner()).result).toBeErr(Cl.uint(106));
    expect(call('refund-many', [Cl.list([Cl.principal(wallet(1))])], wallet(4)).result).toBeOk(Cl.uint(500_000_000n));
    // Refunds finished; the late 7 USDCx, 1 STX and 1,000 sats have no exit.
    expect(ft(USDCX, contractId())).toBe(7_000_000n);
    expect(stx(contractId())).toBe(1_000_000n);
    expect(ft(SBTC, contractId())).toBe(1_000n);
    expect(status().closed).toBeBool(true);
  });

  it('I-3: TERMS say "no one else can add to the reserve", but anyone can, and LAB receives it', () => {
    expect(simnet.transferSTX(2_000_000n, contractId(), wallet(3)).result).toBeOk(Cl.bool(true));
    sendFt(SBTC, SBTC_WHALE, contractId(), 500n);
    expect(status()['reserve-stx']).toBeUint(2_000_000n);
    expect(status()['reserve-sats']).toBeUint(500n);
    expect(status()['reserve-deposited']).toBeBool(false);
    toBurn(DEADLINE);
    expect(call('claim-reserve', [Cl.stringAscii(POOL_URL), Cl.bool(true)], LAB).result).toBeOk(
      Cl.tuple({ usdcx: Cl.uint(0), stx: Cl.uint(2_000_000n), sats: Cl.uint(500n) })
    );
  });

  it('I-4: the reserve can no longer be deposited after DEADLINE even while the seat window is still open', () => {
    sendFt(USDCX, USDCX_WHALE, wallet(1), TARGET);
    toBurn(DEADLINE - 10);
    expect(call('donate', [Cl.uint(TARGET), Cl.bool(true)], wallet(1)).result).toBeOk(Cl.uint(TARGET));
    toBurn(DEADLINE + 5);
    expect(status()['failure-at']).toBeUint(DEADLINE - 10 + 12_960);
    expect(call('deposit-reserve', [Cl.uint(RSTX), Cl.uint(RSATS)], FUNDRAISER).result).toBeErr(Cl.uint(113));
  });
});