grant and refund

Four functions are the owner's: grant, revoke, setPrice and retire. refund is for any wallet. Each signs one transaction with the client's signer, submits it, follows it until it confirms and resolves to its status, a TxStatus: { id, status, signature }.

grant#

grant gives an enclave the key of a model the signer owns. It wraps the model key to the enclave on the device and signs grant_by_owner.

TypeScript
const status = await voynich.grant(model.address, enclave, resume.modelKey)
TypeScript
grant(model: string, enclave: string, modelKey: Uint8Array, options?: { signal?: AbortSignal }): Promise<TxStatus>
FieldMeaning
modelstringrequired

The model's name or address.

enclavestringrequired

The enclave's address or its signing key.

modelKeyUint8Arrayrequired

The 32-byte model key from the sealing's state.

Before the key is wrapped, the client reads the Config, the Model, the Enclave and its attestation record from the chain and requires that:

  • the model is sealed or live and the signer is its owner
  • the record is at the address derived from the enclave's signing key, owned by the configured attestation program, in the configured layout, and names that key
  • the record is in force at the current slot
  • its measurement is the Enclave's and is in the model's allowed measurements

Only then is the key encrypted to the enclave's encryption key, read from the chain. The wrapped key, never the key itself, goes to the API.

The first grant makes the model live.

CodeWhen
WALLET_REQUIREDThe client has no signer.
OWNER_REQUIREDThe signer is not the model's owner.
MODEL_NOT_LIVEThe model is uploading or retired.
ENCLAVE_MISMATCHThe API answered with another enclave than the one asked for.
PROGRAM_MISMATCH, INVALID_CHAIN_ACCOUNT, MODEL_MISMATCH, INVALID_ATTESTATIONAs in call.
TRANSACTION_FAILED, TRANSACTION_EXPIREDThe transaction did not land.
ApiClientErrorMODEL_NOT_FOUND, ENCLAVE_NOT_FOUND, or another API error code.

How a granted enclave passes the key on without the owner is in Grants.

revoke#

revoke marks one enclave's grant for a model revoked. It signs revoke_grant. What a revoked grant stops is in Grants.

TypeScript
const status = await voynich.revoke('sketch-32', enclave)
TypeScript
revoke(model: string, enclave: string, options?: { signal?: AbortSignal }): Promise<TxStatus>
FieldMeaning
modelstringrequired

The model's name or address.

enclavestringrequired

The enclave's address or its signing key.

CodeWhen
WALLET_REQUIREDThe client has no signer.
ApiClientError with ENCLAVE_NOT_FOUNDNo enclave has this address or signing key.
ApiClientError with MODEL_NOT_FOUNDNo model has this name or address.
ApiClientError with GRANT_REQUIREDThe enclave holds no grant for the model.
ApiClientError with SIMULATION_FAILEDThe signer is not the model's owner.
TRANSACTION_FAILED, TRANSACTION_EXPIREDThe transaction did not land.

setPrice#

setPrice sets a model's price, its mint and the operator share together. It signs set_price. Calls that open after it pay the new price.

TypeScript
const price = { amount: '100000', mint: null, decimals: 9, symbol: 'SOL' }

const status = await voynich.setPrice('sketch-32', price, 3000)
TypeScript
setPrice(model: string, price: Money, operatorShareBps: number, options?: { signal?: AbortSignal }): Promise<TxStatus>
FieldMeaning
modelstringrequired

The model's name or address.

priceMoneyrequired

The price of one call: amount in base units as a decimal string, mint (an SPL Token mint address, or null for SOL), and the mint's decimals and symbol.

operatorShareBpsnumberrequired

The operator's share of the price, in basis points, 0 to 10,000. With the protocol share it is at most 10,000.

CodeWhen
WALLET_REQUIREDThe client has no signer.
ApiClientError with MODEL_NOT_FOUNDNo model has this name or address.
ApiClientError with VALIDATION_ERRORThe price or the share does not have the shape above.
ApiClientError with SIMULATION_FAILEDThe signer is not the model's owner, or the operator share plus the protocol share is above 10,000.
TRANSACTION_FAILED, TRANSACTION_EXPIREDThe transaction did not land.

retire#

retire closes a model to new calls and new grants. It signs retire_model.

TypeScript
const status = await voynich.retire('sketch-32')
TypeScript
retire(model: string, options?: { signal?: AbortSignal }): Promise<TxStatus>
CodeWhen
WALLET_REQUIREDThe client has no signer.
ApiClientError with MODEL_NOT_FOUNDNo model has this name or address.
ApiClientError with SIMULATION_FAILEDThe signer is not the model's owner.
TRANSACTION_FAILED, TRANSACTION_EXPIREDThe transaction did not land.

refund#

refund returns the whole escrow of a call that passed its deadline without a receipt.

TypeScript
const refunded = await voynich.refund(callAddress)
console.log(refunded.status, refunded.signature)
TypeScript
refund(call: string, options?: { signal?: AbortSignal }): Promise<TxStatus>

The escrow goes to the call's caller whoever signs. The signer pays the transaction fee.

CodeWhen
WALLET_REQUIREDThe client has no signer.
ApiClientError with CALL_NOT_FOUNDNo call has this address.
ApiClientError with CALL_NOT_REFUNDABLEThe deadline has not passed.
ApiClientError with CALL_NOT_OPENThe call settled or was refunded already.
TRANSACTION_FAILED, TRANSACTION_EXPIREDThe transaction did not land.

Calls that can be refunded are the ones with status: "refundable" in account.

send#

send is what the functions above end with: it signs a build with the client's signer, submits it and follows it until it confirms. With api, the typed client of every build route, it sends any transaction the API builds. api and send are members of a client made with createVoynich.

TypeScript
import { createVoynich } from 'voynich'

const voynich = createVoynich({ apiUrl: 'https://<api host>', signer: wallet })

const build = await voynich.api.refundCall(callAddress, { wallet: wallet.publicKey.toBase58() })
const status = await voynich.send(build)
TypeScript
send(build: Build, localSigners?: Keypair[], signer?: WalletSigner | Keypair, signal?: AbortSignal): Promise<TxStatus>

The wallet signs first. Keys in localSigners that the transaction requires sign the transaction the wallet returns. signer replaces the client's signer for this one transaction. send throws TRANSACTION_FAILED or TRANSACTION_EXPIRED with the reason when the transaction does not land.

The build routes are in HTTP API: Models and what each does on chain is in Program: Instructions. The owner's tasks in order are in Manage a model.