Instructions

Reading this page

Each instruction below gives its data layout, its accounts in the order the program reads them, the checks it makes with the error each one raises, what it changes, and its event. Offsets count from the first byte of the instruction data, where the tag sits. Program reference gives the encodings.

The account tables list the instruction’s own accounts. Every instruction takes two more after them, both read-only: the event authority and the curta program. The builders in @curta/sdk append them, and each builder’s signature is given with its instruction.

Checks every instruction makes

These run on every instruction, and the tables further down list what each instruction checks beyond them.

Each Config, Model, Run, weight or vault account an instruction takes is checked by type:

init_config

Creates the Config account and the FeeVault, and sets the turn reward and the protocol share rate. It runs once per program.

Data

Accounts

Checks

What it changes

• Creates config at 128 bytes and feeVault at 8 bytes, both owned by the program and rent-exempt. Lamports already sitting at either address count toward its rent.
• Writes the Config: tag, authority, FeeVault address, turn reward, protocol share rate and both bumps.
• Writes the tag CURTAFEE into the FeeVault.

Event

Emits a init_config event, action 0: primary is the Config, actor the authority, related the FeeVault. Values: turn reward, protocol share basis points. Events gives the byte layout.

set_config

Sets the turn reward and the protocol share rate. A run records both when it opens, so the new values apply to runs opened afterwards.

Data

Accounts

Checks

What it changes

• Writes the turn reward at offset 72 and the protocol share rate at offset 80 of the Config.

Event

Emits a set_config event, action 1: primary is the Config, actor the authority, related the FeeVault. Values: turn reward, protocol share basis points. Events gives the byte layout.

create_model

Writes a Model account in an account created earlier in the transaction, with its configuration, name, royalty, weights hash and one descriptor per weight account, and creates the model’s vault.

Data

Accounts

Checks

What it changes

• Creates modelVault at 8 bytes with the tag CURTAVLT.
• Writes the Model: tag, publisher, vault address, configuration, section count, vault bump, royalty, weights hash, total weight bytes, the slot, the name and the section descriptors, each with zero bytes written.

Event

Emits a create_model event, action 2: primary is the model, actor the publisher, related the ModelVault. Values: royalty, total weight bytes, section count. Events gives the byte layout.

write_weights

Writes one chunk of a section into its weight account and sets the chunk’s bit in the upload bitmap. A chunk is 800 bytes; the last chunk of a section is the remainder. Chunks arrive in any order, and sending a chunk again with the same bytes succeeds without counting twice.

Data

Accounts

Checks

What it changes

• On the first write to a section, writes the weight account’s header: the tag CURTAWGT, the model’s address and the section index.
• Copies the chunk to offset 2,048 + offset of the weight account and sets bit (offset / 800) of the bitmap that starts at byte 64.
• Adds the chunk’s length to the section’s bytes-written counter in the Model. A chunk whose bit is already set leaves the counter as it is.

Event

Emits a write_weights event, action 3: primary is the model, actor the publisher, related the weight account. Values: section, offset, chunk length, bytes written in the section so far. Events gives the byte layout.

seal_model

Takes one step of sealing. A step hashes the next 65,536 bytes of the section being sealed into the model’s running hash, stopping at the section’s end, and on section zero also validates 512 tokenizer entries. The step that finishes the last section compares the running hash with the weights hash and seals the model.

Data

Accounts

Checks

What it changes

• Sets the running hash to SHA-256 of the previous running hash followed by the step’s bytes. The running hash starts as 32 zero bytes.
• Sets the sealing flag, which closes the model to write_weights, and adds one to the seal step.
• On section zero, advances the tokenizer validation cursor by 512 entries, up to the vocabulary size. Section zero is finished when its bytes are hashed and the cursor has reached the vocabulary size.
• Advances the seal byte offset, or moves to the next section with the offset at zero when the section is finished.
• When the last section is finished and the hashes match, sets the sealed flag and clears the sealing flag.

Event

Emits a seal_model event, action 4: primary is the model, actor the publisher, related the weight account. Values: section, byte offset reached in it, bytes hashed in this step, sealed (1 when this step sealed the model). Events gives the byte layout.

set_royalty

Sets the model’s royalty per generated token. A run records the royalty when it opens, so the new value applies to runs opened afterwards.

Data

Accounts

Checks

What it changes

• Writes the royalty at offset 120 of the Model.

Event

Emits a set_royalty event, action 5: primary is the model, actor the publisher, related the all-zero address. Values: royalty. Events gives the byte layout.

claim_royalties

Moves lamports from the model’s vault to the publisher. An amount of zero claims everything above the vault’s rent.

Data

Accounts

Checks

What it changes

• Moves the amount from modelVault to publisher. The vault keeps its rent.

Event

Emits a claim_royalties event, action 6: primary is the model, actor the publisher, related the ModelVault. Values: amount claimed. Events gives the byte layout.

open_run

Opens a run on a sealed model, in a run account created earlier in the transaction. The run account arrives zero-filled at its exact size and holds its rent plus the budget. The run records the turn reward, the royalty and the protocol share rate in force, and the cost of its first turn.

Data

Accounts

The run account’s size comes from the model’s configuration, the prompt’s byte length and maxTokens; Accounts gives the formula, and client.quote returns it as runAccountSize with the rent and the budget for the whole run. A program opens a run by CPI with its own PDA as the opener, as Call from a program shows.

Checks

What it changes

• Writes the working state: its header, the parameters and the prompt.
• Writes the run header: tag, opener, model, Config address, protocol share rate, max tokens, temperature, prompt length, seed, turn reward, royalty, budget deposited and remaining (both the budget), the working state’s length, and the slot as both opened slot and last activity slot.
• Computes the cost of the first turn and stores it. The state is running when the budget covers it, starved otherwise.
• Adds one to the model’s count of runs opened.

Event

Emits a open_run event, action 7: primary is the run, actor the opener, related the model. Values: budget, max tokens, temperature Q16, seed, 0, state. Events gives the byte layout.

turn

Advances the run’s forward pass as far as one transaction allows, pays the signer the turn reward from the run’s budget, and accrues the royalty and the protocol share in the run.

Data

Accounts

With one matrix account the event authority is account 6 and the program account 7; with two they are 7 and 8. The matrix sections a turn reads follow from the run’s working state alone. The SDK computes them with the core’s planTurn, as SDK reference describes, and client.turn(run) builds the whole instruction. The turn write-locks two accounts, the run and the cranker, so turns on different runs of one model execute in parallel.

Checks

What it changes

• Plans the turn from the working state: which matrix sections it reads and how many tokens it can complete at most. The reserve is the turn reward, plus the royalty for that many tokens, plus the protocol share those add.
• When the budget remaining is below the reserve: sets the state to starved, stores the reserve as the cost of the next turn, and ends. The transaction succeeds, no computation runs and no reward is paid.
• Otherwise runs the core on the working state, which advances the forward pass and appends the id and the text bytes of every token it completes.
• Charges the budget: the turn reward, the royalty times the tokens this turn completed, and the growth of the protocol share, which is floor((rewards paid + royalties accrued) × rate / 10,000) less the share already accrued.
• Writes the budget remaining, rewards paid, royalties accrued, protocol share accrued, the turn count plus one, the generated token count, the slot as last activity slot, and the cost of the next turn.
• Sets the state: complete when the run reached the end token or its max tokens, starved when the budget is below the next turn’s cost, running otherwise.
• Moves the turn reward from the run account to the cranker.

Event

Emits a turn event, action 8: primary is the run, actor the cranker, related the model. Values: turn count after the turn, reward paid, royalty accrued by this turn, protocol share accrued by this turn, budget remaining, state. The token list carries the id of every token the turn completed. A turn that starved the run carries the unchanged turn count, zeros for the three amounts, and no tokens. Events gives the byte layout.

fund

Moves SOL from the signer into the budget of a running or starved run. A starved run whose budget now covers its next turn returns to running.

Data

Accounts

Checks

What it changes

• Adds the amount to the budget deposited and the budget remaining.
• Sets the state: running when the budget remaining covers the cost of the next turn, starved otherwise.
• Transfers the amount from funder to the run account through the System program.

Event

Emits a fund event, action 9: primary is the run, actor the funder, related the model. Values: amount, budget remaining, state. Events gives the byte layout.

cancel

Marks a running or starved run cancelled. Turns stop, and the royalty and protocol share accrued so far stay owed until settlement.

Data

Accounts

Checks

What it changes

• Sets the state to cancelled.

Event

Emits a cancel event, action 10: primary is the run, actor the opener, related the model. Values: budget remaining. Events gives the byte layout.

settle

Pays out what a complete or cancelled run accrued: the royalty to the model’s vault and the protocol share to the FeeVault. It runs once per run.

Data

Accounts

Checks

What it changes

• Adds the run’s generated tokens to the model’s tokens settled and its accrued royalty to the model’s royalties settled.
• Sets the run’s settled flag.
• Moves the accrued royalty from the run account to modelVault and the accrued protocol share to feeVault.

Event

Emits a settle event, action 11: primary is the run, actor the caller, related the model. Values: royalty paid, protocol share paid, turn rewards the run paid in total, tokens generated. Events gives the byte layout.

close_run

Closes a settled run and returns every lamport in the account to the opener: the unspent budget and the rent.

Data

Accounts

Checks

What it changes

• Moves the run account’s whole balance to the opener.
• Resizes the run account to zero bytes and assigns it to the System program.

Event

Emits a close_run event, action 12: primary is the run, actor the opener, related the model. Values: lamports returned. Events gives the byte layout.

Sending an instruction

The builders return a TransactionInstruction. client.send puts a compute unit limit of 1,400,000 in front, signs with the client’s wallet and any extra signers, and resolves with the signature once the transaction is confirmed.

import { fundInstruction } from '@curta/sdk'

const signature = await curta.send([
  fundInstruction({ funder: curta.wallet!.publicKey, run, amountLamports: 1_000_000n }),
])