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.
const status = await voynich.grant(model.address, enclave, resume.modelKey)grant(model: string, enclave: string, modelKey: Uint8Array, options?: { signal?: AbortSignal }): Promise<TxStatus>modelstringrequiredThe model's name or address.
enclavestringrequiredThe enclave's address or its signing key.
modelKeyUint8ArrayrequiredThe 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
sealedorliveand 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.
| Code | When |
|---|---|
WALLET_REQUIRED | The client has no signer. |
OWNER_REQUIRED | The signer is not the model's owner. |
MODEL_NOT_LIVE | The model is uploading or retired. |
ENCLAVE_MISMATCH | The API answered with another enclave than the one asked for. |
PROGRAM_MISMATCH, INVALID_CHAIN_ACCOUNT, MODEL_MISMATCH, INVALID_ATTESTATION | As in call. |
TRANSACTION_FAILED, TRANSACTION_EXPIRED | The transaction did not land. |
ApiClientError | MODEL_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.
const status = await voynich.revoke('sketch-32', enclave)revoke(model: string, enclave: string, options?: { signal?: AbortSignal }): Promise<TxStatus>modelstringrequiredThe model's name or address.
enclavestringrequiredThe enclave's address or its signing key.
| Code | When |
|---|---|
WALLET_REQUIRED | The client has no signer. |
ApiClientError with ENCLAVE_NOT_FOUND | No enclave has this address or signing key. |
ApiClientError with MODEL_NOT_FOUND | No model has this name or address. |
ApiClientError with GRANT_REQUIRED | The enclave holds no grant for the model. |
ApiClientError with SIMULATION_FAILED | The signer is not the model's owner. |
TRANSACTION_FAILED, TRANSACTION_EXPIRED | The 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.
const price = { amount: '100000', mint: null, decimals: 9, symbol: 'SOL' }
const status = await voynich.setPrice('sketch-32', price, 3000)setPrice(model: string, price: Money, operatorShareBps: number, options?: { signal?: AbortSignal }): Promise<TxStatus>modelstringrequiredThe model's name or address.
priceMoneyrequiredThe 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.
operatorShareBpsnumberrequiredThe operator's share of the price, in basis points, 0 to 10,000. With the protocol share it is at most 10,000.
| Code | When |
|---|---|
WALLET_REQUIRED | The client has no signer. |
ApiClientError with MODEL_NOT_FOUND | No model has this name or address. |
ApiClientError with VALIDATION_ERROR | The price or the share does not have the shape above. |
ApiClientError with SIMULATION_FAILED | The signer is not the model's owner, or the operator share plus the protocol share is above 10,000. |
TRANSACTION_FAILED, TRANSACTION_EXPIRED | The transaction did not land. |
retire#
retire closes a model to new calls and new grants. It signs retire_model.
const status = await voynich.retire('sketch-32')retire(model: string, options?: { signal?: AbortSignal }): Promise<TxStatus>| Code | When |
|---|---|
WALLET_REQUIRED | The client has no signer. |
ApiClientError with MODEL_NOT_FOUND | No model has this name or address. |
ApiClientError with SIMULATION_FAILED | The signer is not the model's owner. |
TRANSACTION_FAILED, TRANSACTION_EXPIRED | The transaction did not land. |
refund#
refund returns the whole escrow of a call that passed its deadline without a receipt.
const refunded = await voynich.refund(callAddress)
console.log(refunded.status, refunded.signature)refund(call: string, options?: { signal?: AbortSignal }): Promise<TxStatus>The escrow goes to the call's caller whoever signs. The signer pays the transaction fee.
| Code | When |
|---|---|
WALLET_REQUIRED | The client has no signer. |
ApiClientError with CALL_NOT_FOUND | No call has this address. |
ApiClientError with CALL_NOT_REFUNDABLE | The deadline has not passed. |
ApiClientError with CALL_NOT_OPEN | The call settled or was refunded already. |
TRANSACTION_FAILED, TRANSACTION_EXPIRED | The 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.
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)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.