Developer reference
On-chain interfaces for each system — opcodes, enums and how the contracts talk. For integrators and the curious; you don’t need any of this to play.
Ton Race Game
What it is
The core exploration game: pilot a ship deeper into a triangular coordinate grid, open cells for RUDA rewards, and bank them — or crash back to the entrance. It is one consumer of the GM Ultimate platform; every reward is RUDA minted through the GameManager + Retranslator pipe.
- Ship — your player contract (one per wallet, deterministic address); holds position, HP, max HP, fuel, rewards.
- Coordinate cell — one contract per (x, y), deployed on demand; holds HP, jetton reward, and the first explorer.
- Cone — y is depth (entrance y = 0); a cell is reachable only when |x| ≤ y.
- First explorer — the first ship to open a cell; only it may withdraw that cell's TON / jetton.
- Fuel — TON gas funds ordinary moves; enriched fuel (a reserved resource) funds fast travel (a jump to depth y costs y·(y−1)/2).
On-chain interface
Backed by ship.tolk (one per user), coordinate_cell.tolk (one per (x, y)) and game.tolk; rewards/upgrades route through the GameManager + Retranslator pipe. Opcodes (from deployment.json):
| Opcode | Hex | Direction | Meaning |
|---|---|---|---|
| OP_MOVE | 0x6ecc3df6 | user | Step one row deeper (Left / Up / Right / Exit — see MoveMode). |
| OP_SET_SESSION_KEY | 0x5e55104b | user | Install a browser session key for gasless moves within a budget. |
| OP_REQUEST_TO_FAST_TRAVEL | 0x8d2f1ca4 | user | Request a fast-travel jump straight to a chosen (x, y). |
| OP_TRAVEL_TO_CC | 0x4b13d2f0 | internal | Ship → coordinate cell, executing a fast-travel jump. |
| OP_LAUNCH_HARD_TRAVEL | 0x7dbcd1dc | user | Start hard travel — auto-advance several rows in one transaction. |
| OP_HARD_TRAVEL | 0x2f168b85 | internal | Per-row hard-travel step. |
| OP_REQUEST_TO_HARD_TRAVEL | 0x18dd41ae | internal | Cell → ship continuation of a hard-travel run. |
| OP_HARD_TRAVEL_MOVE_END | 0x8e7f9a0b | internal | Terminates a hard-travel run when a limit is hit. |
| OP_MOVE_SHIP_TO_CC | 0xeafb35a2 | internal | Ship → coordinate cell for an ordinary move (combat resolution). |
| OP_REQUEST_TO_MOVE | 0xf2a70b07 | internal | Cell → ship request that drives the next move. |
| OP_MOVE_END | 0xb2a06139 | internal | Settles a move's outcome back on the ship. |
| OP_RESET_SHIP | 0x6a3b8fdd | user | Clear the current run, return the ship to (0, 0). |
| OP_REQUEST_MINT | 0xf5cc90ff | user | Claim pending rewards → triggers the RUDA mint pipe. |
| OP_REQUEST_SHIP_TO_MINT | 0x53035644 | internal | Ship → game, forwarding a mint request. |
| OP_FORWARD_MINT_REQUEST | 0xf62ed009 | internal | Forward a mint request up to GameManager (→ Retranslator). |
| OP_SHIP_UPGRADE | 0x7d37523d | internal | Apply a hull upgrade (raises HP / max HP) after a RUDA transfer. |
| OP_FAST_TRAVEL_UPGRADE | 0x5a1f0b21 | internal | Add enriched fuel after a RUDA transfer. |
| OP_JETTON_USED | 0xd7610922 | internal | Notifies that staked RUDA was consumed for an upgrade. |
| OP_WITHDRAW_TON | 0xe06f1de3 | user | First explorer withdraws the cell's accumulated TON. |
| OP_WITHDRAW_JETTON | 0xb3cff37d | user | First explorer withdraws the cell's accumulated jetton (RUDA). |
| OP_WITHDRAW_NFT | 0x09e971a8 | user | First explorer withdraws an NFT held by the cell. |
| OP_REQUEST_SHIP_ADDRESS | 0xf0469aee | read | Ask the game for a ship's deterministic address. |
| OP_REQUEST_COORDINATE_CELL_ADDRESS | 0x213f6f8a | read | Ask the game for a cell's deterministic address. |
| OP_RESPONSE_ADDRESS | 0x33226fce | response | Address reply for the two address requests above. |
| OP_RETURN_EXCESSES_BACK | 0xd53276db | response | Return unspent TON to the initiator. |
| OP_LITERALY_ANYTHING | 0x0a1b2c3d | internal | Catch-all marker opcode used inside the pipe. |
- MoveMode — direction of a step (each increases depth y by 1): LEFT (0) lowers x; UP (1) keeps x; RIGHT (2) raises x; EXIT (3) safe-exits if ship HP > cell HP.
- UniqueResult — the verdict outcome: SAFE_EXIT (0) full reward + reset; CRASH (1) ship destroyed, 10% reward + reset; CONTINUE (2) survived, HP reduced.
- JettonUsageMode — what a RUDA transfer buys (in the forward payload): SHIP_UPGRADE (0) raises max HP; FAST_TRAVEL_UPGRADE (1) adds enriched fuel.
Errors a player can hit are shown in-app as a rejected action (e.g. a move while one is already confirming). The full error-code list lives in deployment.json and the repo systems reference.
How to use it in UAT
Everything is prepared by the backend and signed by your TonConnect wallet (or, for gasless moves, your browser session key).
- Deploy & launch: My ship → “Create your ship”, then “Launch ship” to enter a run.
- Move: click a forward panel (Left / Up / Right); the controls lock until the move confirms on-chain.
- Fast travel: enter (x, y) and press Go (spends enriched fuel). Hard travel: set dir/gas/hp/turns and launch (attach ≈ 1.12 TON).
- Upgrade: enter a RUDA amount, pick Reinforce Hull or Refuel Enriched; your wallet signs a RUDA transfer to the GameManager.
- Claim / reset: “Claim mint” credits pending RUDA; “Reset ship” clears the run.
- Withdraw cell rewards: open a cell on the map; if you're its first explorer, Withdraw TON / Withdraw jetton.
Soulless Slot Machine
What it is
A one-button game of pure chance: stake a token, roll three reels, and a matching row wins RUDA or an NFT. The outcome is decided on-chain — the site can't predict or claim a win. RUDA wins are minted through the GameManager + Retranslator pipe.
- Reels — 3 reels, each lands on a symbol (0, 7 or X); X is tied to NFT-tier rewards.
- Roll — one spin; you attach a little TON to fund it, and any excess is refunded.
- Stake — RUDA roll (the native token) or a custom jetton.
- Escrow — a custom-jetton stake is held in escrow and returned on a winning row; a native RUDA stake is burned to fund the roll.
On-chain interface
Backed by soulless_slot_machine.tolk and three ephemeral per-roll slots (ssm_slot.tolk). NFT wins mint via the nft printer. Opcodes (from deployment.json):
| Opcode | Hex | Direction | Meaning |
|---|---|---|---|
| OP_TRANSFER_NOTIFICATION | 0x7362d09c | user | Jetton transfer notification carrying your stake + roll request (TEP-74). |
| OP_JETTON_USED | 0xd7610922 | internal | Marks the staked jetton as consumed for the roll. |
| OP_ROLL_STEP | 0x55310001 | internal | SSM → slot0, then slot_i → slot_{i+1}; accumulates symbols. |
| OP_ROLL_RESULT | 0x55320002 | internal | Last slot → SSM: the completed 3-symbol result. |
| OP_R1 | 0x52310001 | internal | Wrapped request into the GM pipe (for a RUDA mint win). |
| OP_FORWARD_MINT_REQUEST | 0xf62ed009 | internal | Forward a RUDA mint request up to GameManager. |
| OP_MINT_NFT | 0x4d6e6674 | internal | Mint an NFT reward via the printer. |
| OP_ASK_TO_TRANSFER | 0x0f8a7ea5 | internal | Standard jetton transfer op (e.g. escrow return). |
| OP_RETURN_EXCESSES_BACK | 0xd53276db | response | Refund attached-TON excess to the player. |
| OP_SET_SSM_CONFIG | 0x5535e701 | owner | Owner configures the machine. |
| OP_SSM_BURN_STAKE | 0x5362726e | internal | Burn a native RUDA stake that funded the roll. |
- SsmSymbol — the rolled symbol (packed 2 bits per reel): ZERO (0) nothing; SEVEN (1); X (2) the NFT-tier driver.
- SsmRewardKind — what a settled roll pays: NOTHING (0); NFT (1); MINT_RUDA (2); RETURN_ESCROW (3) returns a custom-jetton stake on a win.
A custom roll rejected with an “invalid amount” error means the stake wasn't the exact allowed amount. Full error codes live in deployment.json / the repo systems reference.
How to use it in UAT
Play from the SSM card's inline panel or its own page; your wallet signs every roll.
- Open the machine from the Games list (inline panel) or its dedicated page.
- Pick a mode: RUDA roll (10 / 100 / 1000 RUDA, burned) or Custom jetton (paste the master address, stake the exact allowed amount, escrowed).
- Press “Roll the reels” and sign; ≈ 1 TON is attached to fund the roll (excess refunded). It shows “result pending” while submitting.
- Collect: a win pays tokens to your wallet or an NFT that appears on your Inventory page once minted — nothing to claim by hand.
Anvil (crafting)
What it is
The NFT-item crafting system: combine matching pairs to raise a tier, alloy a multisplav to blend in a new origin, reset type/tier, or melt an item back to RUDA. Recipes are validated by the Retranslator; items mint/edit through the nft printer.
- Item — a TON NFT with a type, a tier (level) and an origin (native RUDA or a custom jetton).
- Multisplav — a special type-5 item; alloying blends the provenance (origins) of sacrificed items into it.
- Provenance — recorded in a Bloom filter (512 bits, k = 3); because it can collide, an alloy may be rejected on-chain even when the UI looks valid.
- Recipe — one of the five anvil operations (see AnvilRecipe).
- Tier caps — generic items cap at tier 10, a multisplav at 64, with a safety cap of 1000.
On-chain interface
The anvil has no standalone contract: validation lives in the Retranslator (so its error codes are in the retranslator group) and item lifecycle runs through the nft printer. Opcodes (from deployment.json):
| Opcode | Hex | Direction | Meaning |
|---|---|---|---|
| OP_ANVIL_COMBINE | 0x416e7643 | internal | Two-item combine (also the multisplav alloy path). |
| OP_ANVIL_TRANSFORM | 0x416e7654 | internal | Single-item transform (reset type / reset tier). |
| OP_ANVIL_MELT | 0x416e764d | internal | Melt an item back to RUDA. |
| OP_PRINTER_ANVIL_APPLY | 0x416e7641 | internal | Printer applies a validated anvil outcome to an item. |
| OP_ANVIL_INIT | 0x416e7601 | internal | Begin an anvil operation on the primary item. |
| OP_ANVIL_HOP | 0x416e7602 | internal | Hop between the two items in a two-item recipe. |
| OP_ANVIL_REPORT_TO_COLLECTION | 0x416e7603 | internal | Report the result up to the collection. |
| OP_SET_NFT_CONTENT_AND_DESTROY | 0x416e7604 | internal | Write the surviving item's content and destroy the sacrifice. |
| OP_ANVIL_DESTROY_FROM_SIBLING | 0x416e7605 | internal | Destroy a sibling item during a recipe. |
| OP_ANVIL_DESTROY | 0x416e7606 | internal | Destroy an item (melt / reset path). |
- AnvilRecipe — the operation: COMBINE (1) merge a matching pair; MULTISPLAV (2) alloy; ZERO_TYPE (3) / ZERO_TIER (4) reset; MELT (5) destroy → RUDA.
- AnvilOutcomeKind — UPDATE (1) edit one item; UPDATE_DESTROY (2) edit primary, destroy sacrifice; MELT (3) destroy → RUDA.
- AnvilTypeSpace — the type slots: GENERIC (0) and MULTISPLAV (5).
An alloy can be rejected on-chain if that origin was already alloyed in (a Bloom-filter collision) — your item is unchanged; pick a different one. Full error codes live in deployment.json.
How to use it in UAT
On the Inventory page, pick a recipe and the item(s) it needs, then craft — one signed message.
- Open the Anvil on the Inventory page.
- Pick a recipe: Combine, Multisplav (alloy), Reset type/tier, Melt → RUDA, or Mint seed (stake 1000 RUDA).
- Pick the primary item (kept/upgraded) and, where needed, a second item to sacrifice.
- Press Craft; your wallet signs once and the result appears in your inventory shortly after.
- Heads-up: an alloy can be rejected on-chain (Bloom collision) even when valid here — just pick a different item.
GameManager + Retranslator
What it is
The platform's spine: a stable pipe + authority (GameManager) plus a swappable brain (Retranslator) that every other system routes through. End users never call it directly; the Admin page reads its state and exposes owner-only config.
- GameManager — the sole on-chain authority (owner/admin of the RUDA minter); forwards requests, embeds no game logic.
- Retranslator — the brain: registries + validation; redeployable/re-pointable without touching GM.
- The pipe — GM wraps a request (R1) into R2 to the Retranslator, which returns R3 that GM emits as R4 to the recipient.
- Registries — the Retranslator knows the jetton minter, the games, and the printer/tools addresses (set by the owner).
On-chain interface
Backed by game_manager.tolk and retranslator.tolk. Opcodes (from deployment.json):
GameManager opcodes
| Opcode | Hex | Direction | Meaning |
|---|---|---|---|
| OP_R1 | 0x52310001 | internal | Inbound request wrapper into the pipe. |
| OP_R2 | 0x52320002 | internal | GM → Retranslator (initiator attested). |
| OP_R3 | 0x52330003 | internal | Retranslator → GM (what to emit). |
| OP_SET_RETRANSLATOR | 0x53455452 | owner | Owner: swap the active Retranslator. |
| OP_REDIRECT_MESSAGE | 0x83449946 | owner | Owner: relay config to the Retranslator (set registries). |
| OP_RETURN_EXCESSES_BACK | 0xd53276db | response | Return unspent TON. |
| OP_TRANSFER_NOTIFICATION_FOR_RECIPIENT | 0x7362d09c | internal | Jetton transfer notification routed for a recipient. |
| OP_LITERALY_ANYTHING | 0x0a1b2c3d | internal | Catch-all marker opcode. |
Retranslator opcodes (selected)
| Opcode | Hex | Direction | Meaning |
|---|---|---|---|
| OP_SET_JETTON_INFO | 0x53455401 | owner | Owner: register the jetton minter/wallet info. |
| OP_SET_GAMES_INFO | 0x7b2c3d4e | owner | Owner: register the games table. |
| OP_SET_TOOLS_INFO | 0x53455403 | owner | Owner: register printer/tools addresses. |
| OP_SET_ALLOW_BURN | 0x7a8b9c0d | owner | Owner: toggle the burn-allow flag. |
| OP_FORWARD_MINT_REQUEST | 0xf62ed009 | internal | Forward a validated mint request. |
| OP_MINT_NEW_JETTONS | 0x00000015 | internal | Mint RUDA (standard jetton mint). |
| OP_REQUEST_BURN | 0x8b9c0d1e | internal | Burn flow (gated by allow-burn). |
| OP_ASK_TO_BURN | 0x595f07bc | internal | Burn flow (gated by allow-burn). |
| OP_JETTON_USED | 0xd7610922 | internal | Mark staked jetton consumed. |
| OP_MINT_NFT | 0x4d6e6674 | internal | Drive the NFT printer. |
| OP_MINT_SBT | 0x4d736274 | internal | Drive the SBT printer. |
| OP_REVOKE_SBT | 0x52766b73 | internal | Revoke a soulbound item. |
| OP_SET_PASSPORT_NICKNAME | 0x536e6963 | owner | Owner-field passport write (nickname). |
- GM/R* carry no enum of their own — they relay the consumers' types (e.g. JettonUsageMode, AnvilRecipe, SsmRewardKind), documented on each system's page.
GM/R* errors are owner/operator-facing (e.g. an unregistered game, a missing registry). The full error-code list lives in deployment.json.
How to use it in UAT
Players use the pipe only indirectly — every move, roll, craft and mint flows through it. The visible surface is the Admin page (owner/admin wallet only).
- Read state on the Admin → Contracts / Retranslator panels (address, version, active flag, wired GM, minter, fee, printers).
- Owner actions (prepare → wallet signs): Set retranslator, Set allow-burn, Set tools info. There is no server key.
UBPS — Universal Belief & Political System
What it is
An on-chain graph of beliefs: author questions and answers, compose belief sets, publish a final Belief, and point your Unit at it — or subscribe to someone else's. UBPS has its own master and does not mint RUDA. (Canonical name: Universal Belief & Political System.)
- Question (Q) — an immutable prompt, address-determined by its text (≤ 127 UTF-8 bytes).
- Answer (A) — an immutable response bound to a question.
- Belief set (BS) — selects answers and nests other sets (a DAG).
- Belief (B) — a root belief set: the public profile a Unit can point at.
- Unit — your contract holding a single pointer; it can point at a Belief, subscribe to another Unit, or be cleared.
- Traverse-up (vote) — a signal sent up the pointer chain to the top belief; each hop is re-funded, the leftover refunded.
On-chain interface
Backed by ubps.tolk (master), question/answer/belief_set/unit.tolk. Opcodes (from deployment.json):
| Opcode | Hex | Direction | Meaning |
|---|---|---|---|
| OP_CREATE_UNIT | 0x55425004 | user | Deploy your Unit through the master (deploy + initial pointer). |
| OP_INIT_UNIT_POINTER | 0x55425014 | internal | Master seeds a new Unit's pointer. |
| OP_ACTIVATE_QUESTION | 0x55425001 | user | Create/activate a question. |
| OP_ACTIVATE_ANSWER | 0x55425002 | user | Create/activate an answer (bound to a question). |
| OP_CREATE_BELIEF_SET | 0x55425003 | user | Create a belief set (or a root Belief). |
| OP_ACTIVATE_QUESTION_MSG | 0x55425011 | internal | Master → question activation message. |
| OP_ACTIVATE_ANSWER_MSG | 0x55425012 | internal | Master → answer activation message. |
| OP_POPULATE_BELIEF_SET | 0x55425013 | internal | Fill a belief set's answers/nested sets. |
| OP_SET_POINTER | 0x55425021 | user | Point your Unit at a Belief, subscribe to a Unit, or clear it. |
| OP_TRAVERSE_UP | 0x55425031 | user | Confirm vote — walk up the pointer chain to the top belief. |
| OP_RETURN_EXCESSES_BACK | 0xd53276db | response | Refund unspent TON. |
| OP_LITERALY_ANYTHING | 0x0a1b2c3d | internal | Catch-all marker opcode. |
- Limits (from deployment.json): up to 100 answers and 20 nested sets per belief set; question/answer text ≤ 127 UTF-8 bytes; an optional set name ≤ 256 bytes. The sets graph is acyclic, but Unit→Unit subscription cycles are allowed.
The main gotcha is permanence: a question or answer cannot be changed once created. Full error codes live in deployment.json.
How to use it in UAT
On the Beliefs page (Create / Edit / View / Settings tabs); every write is signed by your wallet.
- Create your Unit once (Create → “Create my Unit”); the master records it so it's indexed.
- Author the graph: ask a question (permanent, ≤ 127 bytes), add answers, compose a belief set; mark it a root Belief (B) to make it pointable.
- Point / subscribe / clear your Unit on the Edit tab; questions/answers/sets are immutable, so “editing your profile” means composing a new Belief and re-pointing.
- Confirm vote walks a signal up your pointer chain to the top belief; cost scales with chain depth, excess refunded.
- The View tab renders the belief graph; Settings shows indexer health and counts.
Universal Passport (UBP)
What it is
Your soulbound on-chain identity: it holds your reputation (a system field) and your nickname (an owner field). It is a non-transferable item minted/edited through the passport printer under GameManager + Retranslator authority, surfaced alongside your UBPS beliefs.
- Soulbound (SBT-N) — a non-transferable item; a transfer attempt is rejected by the contract.
- Per-field write split — the system writes reputation; the owner writes the nickname; neither op can clobber the other's field.
- Owner-bound — for an owner-field edit, the collection derives the item address from (owner, index), so you can only ever reach your own passport.
On-chain interface
Backed by the universal-passport collection + item contracts (the GM→R* pipe drives them). Opcodes (from deployment.json):
| Opcode | Hex | Direction | Meaning |
|---|---|---|---|
| PassportDeploy | 0x00000001 | internal | Collection system-mint of an owner-bound passport item. |
| PassportOwnerInit | 0x55504900 | owner | Owner self-deploys their passport with empty content. |
| RevokePassportItem | 0x00000004 | internal | Collection forwards a revoke to an item. |
| EditPassportItem | 0x00000007 | internal | System content edit of one item (e.g. reputation). |
| EditPassportOwnerContent | 0x00000008 | internal | Owner-field edit (nickname), owner-bound. |
| SetPassportSystemContent | 0x6f89f5e4 | internal | Collection → item system-field write (merged). |
| SetPassportOwnerContent | 0x6f89f5e5 | internal | Collection → item owner-field write (the nickname). |
| ChangeCollectionAdmin | 0x00000003 | owner | Change the collection admin. |
- Fields — Reputation is a system field (id 0), written by the system; Nickname is an owner field (id 0), written by the owner (a Cell<SnakeString>).
Writing a nickname before the passport exists, or writing reputation as the owner, is rejected. Full error codes live in deployment.json.
How to use it in UAT
On the Beliefs → Passport surface (summarised on the User page).
- Create your passport (“Create my passport”) — it deploys your soulbound passport to hold reputation and nickname.
- Set your nickname (“Set nickname”); the request is bound to your wallet — you can only ever set your own.
- Reputation is a system field — written by the system, not by you, and shown on your passport.