@solworks/poll-sdk

@solworks/poll-sdk

TypeScript SDK for the betmore-core-program Solana/Anchor program (Poll.fun / TG-Bet). Wraps account derivation, instruction building, and transaction sending for V2/V3 (binary) and V4 (multi-outcome, pari-mutuel) bets.

import { SDK } from '@solworks/poll-sdk';

const sdk = SDK.build({ connection, wallet, commitment: 'confirmed' });

The package builds from the program's generated IDL: npm run build copies ../betmore-core-program/target/idl/* + target/types/* into src/, then runs tsc. Re-run it after any program rebuild so the bundled IDL/types match the deployed program — see Regenerating the IDL & types for the full pipeline.

---

V4 bets

A V4 bet is multi-outcome (up to 64 outcomes, each a ≤32-byte ASCII label) and pari-mutuel — the pot is split among backers of the winning outcome at settlement; there are no quoted odds. Every V4 program instruction is exposed two ways:

• sdk.<name>V4(params) — builds, signs, and sends the transaction (returns a signature).
• sdk.instructions.v4.<name>(params) — returns just the instruction, for callers that batch / optimize their own transactions (e.g. program-api's tx builder).

Instruction	rpc method	ix-builder
initialize bet	initializeBetV4	instructions.v4.initializeBet
initialize World Cup bet	initializeWorldCupBetV4	instructions.v4.initializeWorldCupBet
add outcome	addOutcomeV4	instructions.v4.addOutcome
place wager	placeWagerV4	instructions.v4.placeWager
initiate vote	initiateVoteV4	instructions.v4.initiateVote
place vote	placeVoteV4	instructions.v4.placeVote
settle batch	settleBetBatchV4	instructions.v4.settleBetBatch
admin resolve	adminResolveBetV4	instructions.v4.adminResolveBet
admin refund batch	adminRefundBetV4	instructions.v4.adminRefundBet
close bet	closeBetV4	instructions.v4.closeBet
close pool	closePoolV4	instructions.v4.closePool
try cancel wager	tryCancelWagerV4	instructions.v4.tryCancelWager

Addresses: sdk.addresses.betV4.get(wagerId, owner), sdk.addresses.poolAuthorityV4.get(wagerId, owner). Account fetch: sdk.accounts.betV4.single(betAddress). Status enums map via SDK.convertRustEnumValueToTSEnumValue(value, MarketStatus).

---

Resolution modes (and the votingDisabled flag)

A V4 bet resolves in one of three ways, selected at creation:

Mode	How it's created	Who resolves
Community vote (default)	isCreatorResolver: false	Any wagerer can initiateVoteV4 once minimumVoteCount active wagers exist; majority placeVoteV4 decides.
Creator resolver	isCreatorResolver: true	Only the bet creator initiates + casts the deciding vote.
Admin-resolve-only (new)	isCreatorResolver: false, votingDisabled: true	No voting at all — only the protocol admin authority via adminResolveBetV4.

What votingDisabled does

InitializeBetV4Params.votingDisabled?: boolean (default false). When true, the on-chain program rejects every voting instruction — both initiateVoteV4 and placeVoteV4 fail with the VotingDisabled error (surfaced as the message "Voting is disabled for this bet"), for community and creator paths alike. The only way such a bet can reach a resolved state is adminResolveBetV4, which requires the signer to be the protocol's withdraw_authority.

This exists for admin/oracle-resolved markets such as World Cup pools, where the outcome is a real-world result fed by a trusted backend rather than a vote. It closes the pot-drain/collusion vector: with voting hard-disabled, neither the creator nor a colluding set of members can resolve the bet to themselves.

Backward-compatible: omit votingDisabled (or pass false) and the bet behaves exactly as before. The flag is forwarded by both initializeBetV4 and instructions.v4.initializeBet.

Create an admin-resolved bet

const { bet } = await sdk.initializeBetV4({
  question: 'Who will win the World Cup?',
  expectedUserCount: 50,
  minimumVoteCount: 2,        // irrelevant once voting is disabled; keep a valid value (>=2 for non-creator-resolver)
  isCreatorResolver: false,   // creator does NOT resolve
  votingDisabled: true,       // <-- hard-disable all voting; admin-resolve-only
  initialOutcomes: ['Brazil', 'Argentina', /* ... up to 64 ASCII labels <=32 bytes */],
});

Any subsequent initiateVoteV4 / placeVoteV4 on that bet throws VotingDisabled.

Resolve it (protocol admin authority only)

await sdk.adminResolveBetV4({
  bet,                 // PublicKey of the V4 bet
  outcomeIndex: 6,     // winning outcome (0-based, < outcomes.length)
  signers: [adminKeypair],          // must be the protocol withdraw_authority
  payerOverride: adminKeypair.publicKey,
});
// bet.status -> Resolved, bet.resolvedOutcomeIndex -> 6
// (if the winning outcome had zero backers, the program resolves to a refund-all state instead)

adminResolveBetV4 only acts on a bet in Pending/Resolving status. Settlement/payout then runs via settleBetBatchV4 (max 5 users/batch).

---

Operational limits & edge cases (V4)

These are real constraints surfaced by the 48-outcome / 50-wager scale tests. They matter most for large multi-outcome bets like World Cup pools.

Compute budget

Large bets have a big account to deserialize / realloc / iterate, so the 200k default compute is not enough past ~40 outcomes. The SDK raises the compute-unit limit on the heavy V4 methods: initializeBetV4, addOutcomeV4, placeWagerV4, adminResolveBetV4 → 600k; settleBetBatchV4 → 1M. (The limit instruction is fixed-length, so this does not affect tx size.)

Transaction size (legacy txs cap at 1232 bytes)

1. You cannot create a many-outcome bet in a single initializeBetV4 tx. ~40+ string labels as instruction data + accounts + the compute prefix exceed 1232 bytes (real names like "Bosnia and Herzegovina" make it worse). Seed the outcome set incrementally instead — see below.
2. Settlement fits ≤ 3 users per batch. settleBetBatchV4 carries 5 fixed user slots; with 4+ distinct users plus the compute prefix the tx exceeds 1232 bytes. Use usersPerBatch <= 3 — a 50-member pool settles in ceil(50/3) = 17 batches. Same for adminRefundBetV4.

Creating a large-outcome bet (the fix for #1)

Initialize with a couple of outcomes, then addOutcomeV4 the rest before any wager (outcomes lock on the first wager):

const { bet } = await sdk.initializeBetV4({ /* ... */ initialOutcomes: ['Brazil', 'Argentina'], votingDisabled: true });
for (const label of remainingTeams) {        // the other 46 teams
  await sdk.addOutcomeV4({ bet, label, signers: [creator] });
}
// ...then wagers. (All outcomes must be added before the first wager.)

Alternatives if the per-create tx count matters: use short on-chain labels (e.g. flag codes / indices) and map to display names off-chain — outcomeIndex is the canonical key anyway, the label is only for display + the wager label check; or add a batched add_outcomes instruction (program change) to add several labels per tx. (v0 txs + address lookup tables only compress account keys, not the label data, so they don't reliably solve this on their own.)

World Cup pools: initializeWorldCupBetV4 (the chosen fix)

For World Cup pools the program hardcodes the 48 teams (WORLD_CUP_OUTCOME_LABELS in controllers/bet_v4.rs) and exposes a dedicated initialize_world_cup_bet_v4 instruction. The create tx carries no outcome labels — the program seeds all 48 — so a full pool is created in one transaction, with the real team names on-chain. This path always forces votingDisabled: true and non-creator-resolver (pools are admin/oracle resolved), so it can't be misconfigured.

const { bet } = await sdk.initializeWorldCupBetV4({
  question: 'Who will win the World Cup?',
  expectedUserCount: 50,
  minimumVoteCount: 2,   // irrelevant once voting is disabled; keep valid (>=2)
});
// bet.outcomes -> 48 teams (alphabetical), bet.votingDisabled === true

The on-chain label order MUST stay index-aligned with the off-chain team table (api/src/common/world-cup-teams.ts); the backend resolves a pool by mapping the winning team name → outcomeIndex via that table. Append-only once any pool exists on-chain.

Regenerating the IDL & types

src/idl/betmore_core_program.json and src/types/betmore_core_program.ts are committed, generated artifacts — do not hand-edit them. The .ts file is a ~17k-line camelCase type helper Anchor derives from the JSON IDL (see its header comment); the JSON is the canonical IDL. Both are produced by the Anchor program build, not by this package.

The full pipeline after any change to betmore-core-program:

# 1. Rebuild the program (writes target/idl/* and target/types/*)
cd betmore-core-program && anchor build          # or, from repo root: npm run build

# 2. Copy the fresh IDL + types into this package, then compile
cd ../betmore-core-sdk && npm run build          # runs `npm run copy` then `tsc`

npm run build chains copy-idl (cp ../betmore-core-program/target/idl/* src/idl/) and copy-types (cp ../betmore-core-program/target/types/* src/types/) before tsc, so a plain npm run build here always refreshes both files from the latest program build. Run npm run copy on its own to refresh without compiling.

Always regenerate after a program rebuild so the bundled IDL/types match the deployed program. The IDL metadata.version/address in the generated files should match the on-chain program you are targeting.

On-chain notes

• The votingDisabled flag lives on the BetV4 account (carved from reserved padding, so adding it did not change the account size; pre-existing bets deserialize to false).
• Adding the flag + its VotingDisabled error is purely additive to the program — no V3 instruction, account, or error code changed.