Transactions
Every change to the chain that the API offers goes through the same three steps: a build route returns an unsigned transaction, the signers sign it, and it is submitted and followed here. The API never holds a key of the caller's.
- Build
Call one of the nine build routes. It returns a Build.
- Sign
Deserialize
transactionBase64, sign with the wallet, then with any other key inrequiredSigners. - Submit
Send the signed bytes, or the signature of a transaction the wallet sent itself, to
POST /v1/transactions/submit. - Follow
Read
GET /v1/transactions/{id}until the status isconfirmed,finalized,failedorexpired.
Build#
What every build route returns.
idstringrequiredThe build's id. It names the transaction in POST /v1/transactions/submit and GET /v1/transactions/{id}.
transactionBase64base64requiredThe unsigned transaction: a version 0 Solana transaction whose fee payer is the request's wallet. It opens with two Compute Budget instructions, a unit limit measured for this transaction and a unit price, followed by the action's instructions.
blockhashstringrequiredThe recent blockhash the transaction carries.
lastValidBlockHeightintegerrequiredThe last block height at which that blockhash lands.
cosignedbooleanrequiredWhether the API adds a signature of its own. false for every action.
actionstringrequiredThe instruction built. One of the nine actions.
requiredSignersarray of addressesrequiredEvery key that signs the transaction, the request's wallet among them.
fixturebooleanrequiredfalse for a build made against a cluster.
addressesobjectrequiredThe accounts the action is about. Each is present when the action has it: model (address), call (address), weights (array of addresses), uploadKey (address).
The API simulates the transaction before it returns the Build, so a Build in hand passed simulation at the slot it was built.
Actions#
action | Built by | requiredSigners | addresses |
|---|---|---|---|
create_model | POST /v1/models/build | owner, upload key | model, weights, uploadKey |
write_weights | POST /v1/models/{id}/write/build | upload key | model, weights, uploadKey |
seal_model | POST /v1/models/{id}/seal/build | owner, upload key | model, uploadKey |
set_price | POST /v1/models/{id}/price/build | owner | model |
grant_by_owner | POST /v1/models/{id}/grant/build | owner | model |
revoke_grant | POST /v1/models/{id}/revoke/build | owner | model |
retire_model | POST /v1/models/{id}/retire/build | owner | model |
open_call | POST /v1/calls/build | caller | model, call |
refund_call | POST /v1/calls/{id}/refund/build | the wallet that sends it | model, call |
What each instruction checks and does is in Instructions.
Errors from a build#
A build route reads the accounts it needs, assembles the transaction and simulates it. Beside the errors every POST route shares, it can answer:
| Code | Stage | When |
|---|---|---|
MODEL_NOT_FOUND, ENCLAVE_NOT_FOUND, CALL_NOT_FOUND | read | An account the request names does not exist on chain. |
| One of the codes in the next table | simulation | The voynich program refused the transaction in simulation with an error the API has its own code for. |
INSUFFICIENT_FUNDS | simulation | The wallet holds less than the transaction needs. See Funding. |
SIMULATION_FAILED | simulation | The transaction failed in simulation for any other reason, such as another program error. |
PROGRAM_REFUSED | build | The transaction cannot be built as one transaction: it is larger than 1,104 bytes, or its signers are not the ones expected. |
When a program raised the error, the envelope's programError names the program, the error and its number.
Funding#
INSUFFICIENT_FUNDS is not retryable, and its envelope carries funding with the amounts. The API answers it when the simulation fails for lack of lamports and the wallet's balance is below required, which is the transaction's fee plus what the action moves or puts into rent:
action | Lamports beside the fee |
|---|---|
create_model | The Model account's rent (6,000 bytes) and uploadFundingLamports. |
grant_by_owner | The Grant account's rent, when the Grant does not exist yet. |
open_call, price in SOL | The Call account's rent and the price. |
open_call, price in a mint | The Call account's rent, and the rent of the Call's token account when it does not exist yet. |
| any other | None. For write_weights the wallet is the upload key, which pays the fee from the upload funding. |
required is at least the fee plus the rent-exempt minimum of an account with no data. When the payment would leave the wallet below that minimum, the minimum is added to required. Lamport amounts carry mint: null.
For open_call with a price in a mint, the API first reads the caller's associated token account for the mint. When it holds less than the price, the build answers INSUFFICIENT_FUNDS before any transaction is assembled, with funding.mint the price's mint and the amounts in its base units.
| Program error | API code |
|---|---|
ModelNotUploading | MODEL_NOT_UPLOADING |
ModelNotSealed, ModelNotLive | MODEL_NOT_LIVE |
InvalidAttestation | ENCLAVE_EXPIRED |
MeasurementNotAllowed | MEASUREMENT_NOT_ALLOWED |
GrantRequired | GRANT_REQUIRED |
CallNotOpen | CALL_NOT_OPEN |
CallDeadlinePassed | CALL_DEADLINE_PASSED |
CallNotRefundable | CALL_NOT_REFUNDABLE |
UploadIncomplete | UPLOAD_INCOMPLETE |
CiphertextHashMismatch | CIPHERTEXT_HASH_MISMATCH |
InvalidWrappedKey | INVALID_ENVELOPE |
Every other error of the program arrives as SIMULATION_FAILED with its name in programError.name. They are listed in Program errors.
Signing#
The wallet signs first. A wallet can add instructions of its own to a transaction before it signs, so every other key signs the copy the wallet returned, not the bytes of the Build.
- The wallet
The request's
walletsignstransactionBase64as the fee payer. Forwrite_weightsthewalletis the upload key, and it is the only signer. - The other required signers
For
create_modelandseal_modelthe upload key signs the transaction the wallet returned. - Serialize
The signed transaction is at most 1,232 bytes. The Build leaves 128 bytes of that for what the wallet adds.
A Build is good until the block height passes lastValidBlockHeight. After that, build again.
POST /v1/transactions/submit#
Hands a signed Build back to the API. The body takes one of two shapes, chosen by mode.
relay: the API sends the transaction#
POST /v1/transactions/submit
Content-Type: application/json
{
"mode": "relay",
"buildId": "<id of the Build>",
"signedTransactionBase64": "<signed transaction, base64>",
"idempotencyKey": "<1 to 128 characters>"
}modestringrequiredrelay.
buildIdstringrequiredThe Build's id.
signedTransactionBase64base64requiredThe transaction with every required signature.
idempotencyKeystring, 1 to 128 charactersrequiredA key that names this submission. See Idempotency keys.
The API checks the signed copy against the Build, simulates the exact bytes with their signatures verified, records them, and sends them to the cluster. Each later read of the status sends the same bytes again while their blockhash is valid, so the transaction lands once or not at all.
The signed copy is accepted when:
- it deserializes as a transaction of at most 1,232 bytes
- its fee payer is the Build's
wallet, with a valid signature - it contains an instruction of the
voynichprogram - every other instruction belongs to the Compute Budget, System, SPL Token, Associated Token Account or Lighthouse program
wallet-sent: the wallet sent the transaction#
POST /v1/transactions/submit
Content-Type: application/json
{
"mode": "wallet-sent",
"buildId": "<id of the Build>",
"signature": "<transaction signature, base58>",
"idempotencyKey": "<1 to 128 characters>"
}modestringrequiredwallet-sent.
buildIdstringrequiredThe Build's id.
signaturetransaction signaturerequiredThe signature of the transaction the wallet sent to the cluster.
idempotencyKeystring, 1 to 128 charactersrequiredA key that names this submission.
The API records the signature and reads its status from the cluster. It sends nothing itself.
Response#
Both modes return a TxStatus with status submitted and the transaction's signature. The same TxStatus goes out on GET /v1/events as transaction.updated.
Errors#
| Code | Stage | When |
|---|---|---|
VALIDATION_ERROR | validation | The body is neither of the two shapes. |
NOT_FOUND | build | No Build has this buildId. Build again. |
IDEMPOTENCY_CONFLICT | send | The Build was already submitted with another idempotency key. |
PROGRAM_REFUSED | wallet | relay only. The signed copy is not accepted: one of the four conditions above does not hold. message says which. |
A code from Errors from a build, or SIMULATION_FAILED | simulation | relay only. The signed bytes failed in simulation, a missing or invalid signature included. |
Idempotency keys#
A Build is submitted once. idempotencyKey makes a repeated request safe:
- The same
buildIdwith the same key returns the TxStatus of the first submission, as it stands now. Nothing is sent twice. - The same
buildIdwith a different key is refused withIDEMPOTENCY_CONFLICTat stagesend.
The key is any string of 1 to 128 characters. The Build's id serves as one.
GET /v1/transactions/{id}#
Reads the status of a Build. {id} is the Build's id. Each read of a submitted Build looks the transaction up on the cluster once and returns the result. A Build that was not submitted reads built.
Returns a TxStatus.
| Code | Stage | When |
|---|---|---|
NOT_FOUND | confirmation | No Build has this id. |
Next: once the status is confirmed or finalized, read what the transaction changed from its own route, such as GET /v1/models/{id} or GET /v1/calls/{id}.
TxStatus#
idstringrequiredThe Build's id.
statusstringrequiredOne of the seven statuses.
signaturetransaction signatureThe transaction's signature, once it is submitted.
errorTxFailureA TxFailure, when the status is failed or expired.
Statuses#
| Status | The transaction |
|---|---|
built | was built and has not been submitted. |
submitted | was taken by the API and the cluster reports no confirmation of it. |
unconfirmed | was sent by the wallet, and the cluster reports nothing for its signature after the Build's lastValidBlockHeight. The API keeps reading it. |
confirmed | is confirmed by the cluster. |
finalized | is finalized by the cluster. |
failed | landed and the cluster reports an error for it. error says which. |
expired | was sent by the API and its blockhash expired before it landed. Nothing was spent. error.nextStep is to build it again. |
confirmed, finalized, failed and expired are final for a client that follows a transaction. A confirmed transaction reads finalized on a later read.
TxFailure#
stagestringrequiredWhere the transaction failed. One of the six stages below.
messagestringrequiredA sentence that can be shown to a person.
nextStepstringWhat to do next, when the API has something to say.
retryablebooleanrequiredWhether trying again can succeed.
programobjectThe program that raised the error: address (address), code (its number, or null) and name (its name, or null).
| Stage | The transaction failed | In the error envelope it is stage |
|---|---|---|
build | while it was built, or its Build is unknown | build |
wallet-rejected | because the wallet declined to sign | wallet |
wallet-changed | because the copy the wallet signed is not accepted | wallet |
simulation | in simulation | simulation |
send | while it was sent | send |
confirm | on the cluster, or by expiring | confirmation |
A TxStatus read from the API carries stage confirm. The other stages reach a client as the stage of an error envelope from a build route or from POST /v1/transactions/submit.