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.

  1. Build

    Call one of the nine build routes. It returns a Build.

  2. Sign

    Deserialize transactionBase64, sign with the wallet, then with any other key in requiredSigners.

  3. Submit

    Send the signed bytes, or the signature of a transaction the wallet sent itself, to POST /v1/transactions/submit.

  4. Follow

    Read GET /v1/transactions/{id} until the status is confirmed, finalized, failed or expired.

Build#

What every build route returns.

FieldMeaning
idstringrequired

The build's id. It names the transaction in POST /v1/transactions/submit and GET /v1/transactions/{id}.

transactionBase64base64required

The 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.

blockhashstringrequired

The recent blockhash the transaction carries.

lastValidBlockHeightintegerrequired

The last block height at which that blockhash lands.

cosignedbooleanrequired

Whether the API adds a signature of its own. false for every action.

actionstringrequired

The instruction built. One of the nine actions.

requiredSignersarray of addressesrequired

Every key that signs the transaction, the request's wallet among them.

fixturebooleanrequired

false for a build made against a cluster.

addressesobjectrequired

The 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#

actionBuilt byrequiredSignersaddresses
create_modelPOST /v1/models/buildowner, upload keymodel, weights, uploadKey
write_weightsPOST /v1/models/{id}/write/buildupload keymodel, weights, uploadKey
seal_modelPOST /v1/models/{id}/seal/buildowner, upload keymodel, uploadKey
set_pricePOST /v1/models/{id}/price/buildownermodel
grant_by_ownerPOST /v1/models/{id}/grant/buildownermodel
revoke_grantPOST /v1/models/{id}/revoke/buildownermodel
retire_modelPOST /v1/models/{id}/retire/buildownermodel
open_callPOST /v1/calls/buildcallermodel, call
refund_callPOST /v1/calls/{id}/refund/buildthe wallet that sends itmodel, 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:

CodeStageWhen
MODEL_NOT_FOUND, ENCLAVE_NOT_FOUND, CALL_NOT_FOUNDreadAn account the request names does not exist on chain.
One of the codes in the next tablesimulationThe voynich program refused the transaction in simulation with an error the API has its own code for.
INSUFFICIENT_FUNDSsimulationThe wallet holds less than the transaction needs. See Funding.
SIMULATION_FAILEDsimulationThe transaction failed in simulation for any other reason, such as another program error.
PROGRAM_REFUSEDbuildThe 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:

actionLamports beside the fee
create_modelThe Model account's rent (6,000 bytes) and uploadFundingLamports.
grant_by_ownerThe Grant account's rent, when the Grant does not exist yet.
open_call, price in SOLThe Call account's rent and the price.
open_call, price in a mintThe Call account's rent, and the rent of the Call's token account when it does not exist yet.
any otherNone. 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 errorAPI code
ModelNotUploadingMODEL_NOT_UPLOADING
ModelNotSealed, ModelNotLiveMODEL_NOT_LIVE
InvalidAttestationENCLAVE_EXPIRED
MeasurementNotAllowedMEASUREMENT_NOT_ALLOWED
GrantRequiredGRANT_REQUIRED
CallNotOpenCALL_NOT_OPEN
CallDeadlinePassedCALL_DEADLINE_PASSED
CallNotRefundableCALL_NOT_REFUNDABLE
UploadIncompleteUPLOAD_INCOMPLETE
CiphertextHashMismatchCIPHERTEXT_HASH_MISMATCH
InvalidWrappedKeyINVALID_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.

  1. The wallet

    The request's wallet signs transactionBase64 as the fee payer. For write_weights the wallet is the upload key, and it is the only signer.

  2. The other required signers

    For create_model and seal_model the upload key signs the transaction the wallet returned.

  3. 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#

HTTP
POST /v1/transactions/submit
Content-Type: application/json

{
  "mode": "relay",
  "buildId": "<id of the Build>",
  "signedTransactionBase64": "<signed transaction, base64>",
  "idempotencyKey": "<1 to 128 characters>"
}
FieldMeaning
modestringrequired

relay.

buildIdstringrequired

The Build's id.

signedTransactionBase64base64required

The transaction with every required signature.

idempotencyKeystring, 1 to 128 charactersrequired

A 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 voynich program
  • every other instruction belongs to the Compute Budget, System, SPL Token, Associated Token Account or Lighthouse program

wallet-sent: the wallet sent the transaction#

HTTP
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>"
}
FieldMeaning
modestringrequired

wallet-sent.

buildIdstringrequired

The Build's id.

signaturetransaction signaturerequired

The signature of the transaction the wallet sent to the cluster.

idempotencyKeystring, 1 to 128 charactersrequired

A 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#

CodeStageWhen
VALIDATION_ERRORvalidationThe body is neither of the two shapes.
NOT_FOUNDbuildNo Build has this buildId. Build again.
IDEMPOTENCY_CONFLICTsendThe Build was already submitted with another idempotency key.
PROGRAM_REFUSEDwalletrelay 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_FAILEDsimulationrelay 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 buildId with the same key returns the TxStatus of the first submission, as it stands now. Nothing is sent twice.
  • The same buildId with a different key is refused with IDEMPOTENCY_CONFLICT at stage send.

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.

CodeStageWhen
NOT_FOUNDconfirmationNo 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#

FieldMeaning
idstringrequired

The Build's id.

statusstringrequired

One of the seven statuses.

signaturetransaction signature

The transaction's signature, once it is submitted.

errorTxFailure

A TxFailure, when the status is failed or expired.

Statuses#

StatusThe transaction
builtwas built and has not been submitted.
submittedwas taken by the API and the cluster reports no confirmation of it.
unconfirmedwas sent by the wallet, and the cluster reports nothing for its signature after the Build's lastValidBlockHeight. The API keeps reading it.
confirmedis confirmed by the cluster.
finalizedis finalized by the cluster.
failedlanded and the cluster reports an error for it. error says which.
expiredwas 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#

FieldMeaning
stagestringrequired

Where the transaction failed. One of the six stages below.

messagestringrequired

A sentence that can be shown to a person.

nextStepstring

What to do next, when the API has something to say.

retryablebooleanrequired

Whether trying again can succeed.

programobject

The program that raised the error: address (address), code (its number, or null) and name (its name, or null).

StageThe transaction failedIn the error envelope it is stage
buildwhile it was built, or its Build is unknownbuild
wallet-rejectedbecause the wallet declined to signwallet
wallet-changedbecause the copy the wallet signed is not acceptedwallet
simulationin simulationsimulation
sendwhile it was sentsend
confirmon the cluster, or by expiringconfirmation

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.