Instructions

The program has 15 instructions.

InstructionArgumentsSignersDoes
initializeargs: ConfigArgsadminCreates the Config. Sent once by the program's upgrade authority.
set_configargs: ConfigArgsadminChanges the Config.
create_modelargs: CreateModelArgsowner, upload_keyCreates a Model in Uploading, binds its Weights accounts and funds the upload key.
write_weightsoffset: u32, bytes: bytesupload_keyWrites ciphertext bytes into one Weights account.
seal_modelciphertext_sha256: [u8; 32]ownerFixes the ciphertext hash and moves the model to Sealed.
set_priceprice: u64, price_mint: pubkey, operator_share_bps: u16ownerSets a model's price, price mint and operator share.
retire_modelownerMoves a model to Retired. No new calls open.
register_enclaveencryption_key: [u8; 32], endpoint: stringoperator, signing_keyCreates an Enclave from a current attestation record.
refresh_enclaveendpoint: stringsigning_keyCopies the enclave's current attestation record into its Enclave account and sets its endpoint.
grant_by_ownerwrapped_key: bytesowner, payerWrites a Grant from the owner to an enclave and moves the model to Live.
grant_by_enclavewrapped_key: bytessigning_key, payerWrites a Grant from an enclave that holds one to another enclave.
revoke_grantownerMarks a Grant revoked. No new calls open on it.
open_callnonce: u64, input_hash: [u8; 32]callerCreates a Call and moves the model's price into its escrow.
settle_calloutput_hash: [u8; 32], signature: [u8; 64], ed25519_instruction_index: u16payerChecks the enclave's signature, writes the Receipt and pays out the escrow.
refund_callactorReturns the escrow of a call past its deadline to the caller.

Every instruction ends with two accounts that Anchor's event CPI needs: event_authority, the PDA ["__event_authority"], and program, the voynich program itself. Accounts are passed in the order of each table. An optional account that is left out is passed as the program's own address.

The errors named below are in Errors. The events are in Events.

initialize#

Creates the Config. It can be sent once, by the program's upgrade authority.

ArgumentType
attestation_programpubkey
record_layout_versionu8
fee_recipientpubkey
protocol_share_bpsu16
call_deadline_slotsu64
AccountWritableSignerOptionalAddressIs
adminyesyesThe program's upgrade authority. Becomes the Config's admin and pays its rent.
configyesPDA ["config"]The Config, created here.
program_account65H3C7T6C2DmbkR9ssBBmNtqpybWcYwotkkETL4E7RSSThe Voynich program.
program_dataThe program's ProgramData account, which names the upgrade authority.
system_program11111111111111111111111111111111The System program.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The signer is the program's upgrade authority (Unauthorized). The attestation program and the fee recipient are not the default address, the layout version is above 0, the protocol share is at most 10,000 and the deadline is above 0 slots (InvalidConfig).
  • Effects. The Config holds the admin and the five values. Emits ConfigChanged.

set_config#

Changes the Config's five values. The admin stays.

ArgumentType
attestation_programpubkey
record_layout_versionu8
fee_recipientpubkey
protocol_share_bpsu16
call_deadline_slotsu64
AccountWritableSignerOptionalAddressIs
adminyesThe Config's admin.
configyesPDA ["config"]The protocol's Config.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The signer is the Config's admin (Unauthorized). The values pass the same checks as in initialize (InvalidConfig).
  • Effects. The Config holds the new values. Calls that are already open keep the fee recipient, the protocol share and the deadline they opened with. Emits ConfigChanged.

create_model#

Creates a Model in Uploading, binds its Weights accounts to it and moves the upload funding to the upload key.

ArgumentType
namestring
manifestbytes
size_bytesu64
cipherstring
nonce_prefix[u8; 16]
allowed_measurementsVec<[u8; 48]>
priceu64
price_mintpubkey
operator_share_bpsu16
upload_funding_lamportsu64
AccountWritableSignerOptionalAddressIs
owneryesyesThe model's owner. Pays the Model's rent and the upload funding.
upload_keyyesyesA fresh key that will write the ciphertext: system-owned, holding no data, different from the owner.
configPDA ["config"]The protocol's Config.
modelyesPDA ["model", args.name]The Model, created here.
system_program11111111111111111111111111111111The System program.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.

manifest is the manifest's compact UTF-8 JSON, as told in The manifest on chain. After these, the transaction passes the model's Weights accounts in order, each writable, as remaining accounts.

  • Checks. The name is 1 to 32 bytes of lowercase letters and digits in groups joined by single hyphens; the manifest is 1 to 4,096 bytes; size_bytes is above 16; cipher is xchacha20poly1305-64k-v1; there are 1 to 8 allowed measurements; the operator share plus the protocol share is at most 10,000; the upload key is not the owner, is owned by the System program and holds no data (InvalidModel). There are 1 to 8 Weights accounts, each owned by the program, writable, rent-exempt, listed once, at most 10 MiB, with its first 56 bytes zero, and their ciphertext sizes add up to size_bytes (InvalidWeights).
  • Effects. The Model exists with status Uploading. Each Weights account has its header. upload_funding_lamports moves from the owner to the upload key. Emits ModelCreated.

write_weights#

Writes ciphertext bytes into one Weights account. Signed by the upload key alone, so an upload needs no wallet prompt per write.

ArgumentType
offsetu32
bytesbytes
AccountWritableSignerOptionalAddressIs
upload_keyyesThe model's upload key.
modelPDA ["model", model.name]The Model.
weightsyesThe Weights account written to. It is one of the model's.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.

offset counts from the start of that account's ciphertext, not from the start of the model's.

  • Checks. The signer is the model's upload key (Unauthorized). The model is Uploading (ModelNotUploading). The account is one of the model's Weights accounts (InvalidWeights). bytes is not empty and offset plus the length is at most the account's size (InvalidWrite).
  • Effects. The bytes are in the account and written_bytes is the highest end written so far. Writes may land in any order. Writing a range again replaces it. Emits WeightsWritten.

seal_model#

Fixes the ciphertext hash. From here the bytes cannot change.

ArgumentType
ciphertext_sha256[u8; 32]
AccountWritableSignerOptionalAddressIs
owneryesThe model's owner.
modelyesPDA ["model", model.name]The Model.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.

After these, the transaction passes every Weights account of the model in order as remaining accounts.

  • Checks. The signer is the model's owner (Unauthorized). The model is Uploading (ModelNotUploading). The accounts are the model's Weights accounts in order (InvalidWeights). Every account's written_bytes equals its size (UploadIncomplete). The SHA-256 of their ciphertext in order equals ciphertext_sha256 (CiphertextHashMismatch).
  • Effects. The Model holds the hash and the sealing slot, its status is Sealed and its upload key is cleared, so nothing can write to its Weights accounts again. Emits ModelSealed.

set_price#

Sets the price, the price mint and the operator share.

ArgumentType
priceu64
price_mintpubkey
operator_share_bpsu16
AccountWritableSignerOptionalAddressIs
owneryesThe model's owner.
configPDA ["config"]The protocol's Config.
modelyesPDA ["model", model.name]The Model.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.

price_mint is an SPL Token mint, or the default (all-zero) address for SOL.

  • Checks. The signer is the model's owner (Unauthorized). The operator share plus the protocol share is at most 10,000 (InvalidModel).
  • Effects. New calls open at the new price, mint and share. Open calls keep theirs. Emits ModelPriceChanged.

retire_model#

Closes a model to new calls.

AccountWritableSignerOptionalAddressIs
owneryesThe model's owner.
configPDA ["config"]The protocol's Config.
modelyesPDA ["model", model.name]The Model.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The signer is the model's owner (Unauthorized).
  • Effects. The model's status is Retired. open_call, grant_by_owner and grant_by_enclave refuse it. Calls that are open settle until their deadline and refund after it. Emits ModelStatusChanged.

register_enclave#

Creates an Enclave from a current attestation record.

ArgumentType
encryption_key[u8; 32]
endpointstring
AccountWritableSignerOptionalAddressIs
operatoryesyesThe operator's wallet. Pays the Enclave's rent and receives the operator share of its calls.
signing_keyyesThe enclave's signing key, the key the attestation record names.
configPDA ["config"]The protocol's Config.
attestation_recordThe enclave's attestation record.
enclaveyesPDA ["enclave", signing_key]The Enclave, created here.
system_program11111111111111111111111111111111The System program.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The endpoint is 1 to 256 bytes and starts with http:// or https://, and the encryption key is not all zero (InvalidEnclave). The record is owned by the configured attestation program, sits at the address derived from the signing key, has the configured layout, names the signing key, and is unexpired at the current slot (InvalidAttestation). The signing key signs the transaction, so only the enclave that holds it can register it.
  • Effects. The Enclave holds both keys, the operator, the endpoint, the record's address and the record's hardware type, measurement, recorded slot and expiry slot. Emits EnclaveChanged.

refresh_enclave#

Copies the enclave's current attestation record into its Enclave account and sets its endpoint. An enclave sends it after it attests again.

ArgumentType
endpointstring
AccountWritableSignerOptionalAddressIs
signing_keyyesThe enclave's signing key.
configPDA ["config"]The protocol's Config.
attestation_recordThe enclave's attestation record.
enclaveyesPDA ["enclave", signing_key]The Enclave.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The signer is the enclave's signing key (Unauthorized). The endpoint is valid (InvalidEnclave). The record is valid and unexpired (InvalidAttestation).
  • Effects. The Enclave holds the record's current hardware type, measurement, recorded slot and expiry slot, and the endpoint given. Emits EnclaveChanged.

grant_by_owner#

Writes a Grant from the owner to an enclave.

ArgumentType
wrapped_keybytes
AccountWritableSignerOptionalAddressIs
owneryesThe model's owner.
payeryesyesPays the Grant's rent.
configPDA ["config"]The protocol's Config.
modelyesPDA ["model", model.name]The Model.
target_enclavePDA ["enclave", target_enclave.signing_key]The Enclave the grant is made to.
target_attestation_recordThat enclave's attestation record.
grantyesPDA ["grant", model, target_enclave]The Grant, created here or written over.
system_program11111111111111111111111111111111The System program.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The signer is the model's owner (Unauthorized). The model is Sealed or Live (ModelNotSealed). The record passed is the one the target Enclave names and still states the Enclave's hardware type and measurement (InvalidEnclave), and it is valid and unexpired (InvalidAttestation). The measurement is in the model's allowed measurements (MeasurementNotAllowed). The wrapped key is 105 bytes and starts with byte 1 (InvalidWrappedKey).
  • Effects. The Grant holds the wrapped key, the owner as granted_by and the current slot, and is not revoked. A Grant that existed for this model and enclave is written over, which also lifts a revocation. The model's status is Live. Emits GrantChanged and ModelStatusChanged.

grant_by_enclave#

Writes a Grant from an enclave that holds one to another enclave. The owner does not sign.

ArgumentType
wrapped_keybytes
AccountWritableSignerOptionalAddressIs
signing_keyyesThe signing key of the enclave that passes the key on.
payeryesyesPays the Grant's rent.
configPDA ["config"]The protocol's Config.
modelyesPDA ["model", model.name]The Model.
source_enclavePDA ["enclave", signing_key]The Enclave that passes the key on.
source_grantPDA ["grant", model, source_enclave]Its own Grant for this model, not revoked.
source_attestation_recordIts attestation record.
target_enclavePDA ["enclave", target_enclave.signing_key]The Enclave the grant is made to.
target_attestation_recordThat enclave's attestation record.
grantyesPDA ["grant", model, target_enclave]The Grant, created here or written over.
system_program11111111111111111111111111111111The System program.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The signer is the source enclave's signing key (Unauthorized). The model is Live (ModelNotLive). The source and the target are different enclaves (InvalidEnclave). The source holds a Grant for this model that is not revoked (GrantRequired). Both records are the ones their Enclaves name, are valid and are unexpired (InvalidEnclave, InvalidAttestation). Both measurements are in the model's allowed measurements (MeasurementNotAllowed). The wrapped key is 105 bytes and starts with byte 1 (InvalidWrappedKey).
  • Effects. The Grant holds the wrapped key, the source Enclave's address as granted_by and the current slot. Emits GrantChanged.

revoke_grant#

Marks a Grant revoked.

AccountWritableSignerOptionalAddressIs
owneryesThe model's owner.
modelPDA ["model", model.name]The Model.
grantyesPDA ["grant", model, grant.enclave]The Grant to revoke.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The signer is the model's owner (Unauthorized). The Grant belongs to the model.
  • Effects. The Grant's revoked is true. open_call refuses the enclave for this model, and the enclave cannot pass the key on. Calls already open with it settle. Emits GrantChanged.

open_call#

Creates a Call and moves the model's price into its escrow.

ArgumentType
nonceu64
input_hash[u8; 32]
AccountWritableSignerOptionalAddressIs
calleryesyesThe caller. Pays the price and the Call's rent.
configPDA ["config"]The protocol's Config.
modelPDA ["model", model.name]The Model.
enclavePDA ["enclave", enclave.signing_key]The Enclave chosen to answer.
attestation_recordThe enclave's attestation record.
grantPDA ["grant", model, enclave]That enclave's Grant for the model, not revoked.
callyesPDA ["call", caller, nonce]The Call, created here.
mintyesThe model's price mint. Only for a price in a mint.
caller_tokensyesyesThe caller's token account for the mint. Only for a price in a mint.
escrow_tokensyesyesThe Call's associated token account for the mint, created here. Only for a price in a mint.
token_programyesTokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DAThe SPL Token program. Only for a price in a mint.
associated_token_programyesATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knLThe Associated Token program. Only for a price in a mint.
system_program11111111111111111111111111111111The System program.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.

nonce is any number the caller has not used before: it gives the Call its address, ["call", caller, nonce]. For a price in SOL the five token accounts and programs are left out.

  • Checks. The model is Live (ModelNotLive). The enclave's Grant for the model is not revoked (GrantRequired). The record is the one the Enclave names, valid and unexpired (InvalidEnclave, InvalidAttestation), and its measurement is allowed (MeasurementNotAllowed). The operator share plus the protocol share is at most 10,000 (InvalidConfig). For a price in a mint: the mint is the model's price mint, the caller's token account holds that mint, and the escrow account is the Call's associated token account (InvalidTokenAccount).
  • Effects. The Call holds the caller, the model, the enclave, the input hash, the price and mint, the owner, the operator, the fee recipient and both shares as they are now, the opening slot and the deadline slot (the opening slot plus the Config's call_deadline_slots). The price moves from the caller into the escrow. Emits CallOpened.

settle_call#

Checks the enclave's signature, writes the Receipt and pays out the escrow, in one instruction.

ArgumentType
output_hash[u8; 32]
signature[u8; 64]
ed25519_instruction_indexu16
AccountWritableSignerOptionalAddressIs
payeryesyesPays the Receipt's rent and the transaction fee. The enclave's runtime sends it.
configPDA ["config"]The protocol's Config.
modelyesPDA ["model", model.name]The Model.
enclaveyesPDA ["enclave", enclave.signing_key]The Enclave that answered.
attestation_recordThe enclave's attestation record.
callyesPDA ["call", call.caller, call.nonce]The Call being settled.
receiptyesPDA ["receipt", call]The Receipt, created here.
calleryesThe call's caller.
owneryesThe owner recorded in the call.
operatoryesThe operator recorded in the call.
fee_recipientyesThe fee recipient recorded in the call.
instructionsSysvar1nstructions1111111111111111111111111The Instructions sysvar.
escrow_tokensyesyesThe Call's associated token account. Only for a price in a mint.
owner_tokensyesyesThe owner's associated token account. Only for a price in a mint.
operator_tokensyesyesThe operator's associated token account. Only for a price in a mint.
protocol_tokensyesyesThe fee recipient's associated token account. Only for a price in a mint.
caller_tokensyesyesA token account of the caller's for the mint. Only for a price in a mint.
token_programyesTokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DAThe SPL Token program. Only for a price in a mint.
system_program11111111111111111111111111111111The System program.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.

The transaction carries an Ed25519 program instruction before settle_call, and ed25519_instruction_index is its index. That instruction verifies exactly one signature and carries the signature, the enclave's signing key and the 114-byte receipt message in its own data.

  • Checks. The call is Open (CallNotOpen). The current slot is at most the deadline slot (CallDeadlinePassed). The record is the one the Enclave names, valid and unexpired (InvalidEnclave, InvalidAttestation), and its measurement is allowed (MeasurementNotAllowed). The Ed25519 instruction at the index matches the signature, the enclave's signing key and the message built from the Call's address, its input hash and output_hash (InvalidSignature). The caller, owner, operator and fee recipient are the ones the Call recorded (InvalidRecipient). For a price in a mint: the escrow, owner, operator and protocol accounts are associated token accounts of the right wallet and mint (InvalidTokenAccount). The escrow holds the price (InsufficientEscrow).
  • Effects. The operator receives price × operator_share_bps / 10,000, rounded down. The fee recipient receives price × protocol_share_bps / 10,000, rounded down. The owner receives the rest. The Receipt holds the call, model, enclave, both hashes, the signature, the slot and the three payments. The Call's status is Settled, and the model's and the enclave's calls_settled rise by one. For a price in a mint, the escrow token account is closed and its rent returns to the caller. Emits CallSettled.

refund_call#

Returns the escrow of a call that did not settle by its deadline. Anyone can send it; the escrow goes to the caller.

AccountWritableSignerOptionalAddressIs
actoryesWhoever sends the refund: the caller or anyone else.
callyesPDA ["call", call.caller, call.nonce]The Call being refunded.
calleryesThe call's caller. Receives the escrow.
escrow_tokensyesyesThe Call's associated token account. Only for a price in a mint.
caller_tokensyesyesA token account of the caller's for the mint. Only for a price in a mint.
token_programyesTokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DAThe SPL Token program. Only for a price in a mint.
event_authorityPDA ["__event_authority"]The program's event authority.
programThe Voynich program.
  • Checks. The call is Open (CallNotOpen). The current slot is past the deadline slot (CallNotRefundable). The caller account is the Call's caller (InvalidRecipient). For a price in a mint: the escrow is the Call's associated token account and the destination is a token account of the caller's for the mint (InvalidTokenAccount).
  • Effects. The whole price returns to the caller. The Call's status is Refunded. For a price in a mint, the escrow token account is closed and its rent returns to the caller. Emits CallRefunded.