Types and errors

voynich#

ExportKindWhat it is
defaultclientIn Node: call, verify, seal, models, model, enclaves, enclave, grant, revoke, setPrice, retire, refund and account, configured from VOYNICH_API_URL and VOYNICH_KEYPAIR on first use. The functions that sign read VOYNICH_KEYPAIR; the reads do not.
createVoynich(options)functionCreates a client. See Install.
VoynichErrorclassThe error the client throws. See Errors.
preprocessSketch(input)functionTurns a drawing in any accepted form into the 784 numbers a sketch model takes. See call.
VoynichtypeThe client: ReturnType<typeof createVoynich>.
VoynichOptionstypeThe options of createVoynich.
WalletSignertype{ publicKey: PublicKey; signTransaction(transaction: VersionedTransaction): Promise<VersionedTransaction> }
VoynichSignertypeWalletSigner | Keypair
CallOptionstype{ signal?: AbortSignal; onStep?: (step: CallStep) => void; enclave?: string }
CallSteptype'encrypting' | 'awaiting-signature' | 'escrowed' | 'answering' | 'verified'
VerificationtypeThe result of verify.
SealOptions, SealResume, SealProgresstypesThe options, the saved state and the progress of seal.
SketchInputtypereadonly number[] | readonly (readonly number[])[] | Float32Array | Float64Array | { strokes: readonly Stroke[]; width: number; height: number }
Stroketypereadonly (readonly [number, number])[]

Everything in voynich/crypto is exported from voynich as well.

The types of what the API returns (Model, Enclave, Grant, Call, CallAnswer, Receipt, ReceiptView, Money, Manifest, Build, TxStatus and the rest) and ApiClientError come from @voynich/contract. Their fields are on the HTTP API pages.

voynich/crypto#

Bytes are Uint8Array throughout.

ExportSignatureDoes
sealWeights(plaintext, key?, header?) => { key, header, ciphertext, sha256 }Encrypts weights. Draws the key when none is given, and a fresh nonce prefix. With a key and the header of an earlier sealing it produces that sealing's ciphertext again.
weightsCipherRange(header, offset, length) => { offset, length, firstChunk }The ciphertext range that holds a plaintext range: the complete sealed chunks it touches.
openWeightsRange(ciphertextRange, key, header, offset, length) => Uint8ArrayDecrypts a plaintext range from that ciphertext range, authenticating every chunk first.
wrapKey(key, recipientPublicKey) => Uint8ArrayWraps a 32-byte model key to an enclave's encryption key: the 105-byte envelope of a grant.
unwrapKey(envelope, recipientSecret) => Uint8ArrayUnwraps it.
encryptCallInput(plaintext, enclavePublicKey) => Uint8ArrayThe input envelope of a call.
decryptCallInput(envelope, enclaveSecret) => Uint8ArrayOpens it.
encryptCallOutput(plaintext, callerPublicKey) => Uint8ArrayThe output envelope of a call.
decryptCallOutput(envelope, callerSecret) => Uint8ArrayOpens it.
receiptMessage(call, inputHash, outputHash) => Uint8ArrayThe 114 bytes an enclave signs.
signReceipt(seed, call, inputHash, outputHash) => Uint8ArraySigns them with an Ed25519 seed.
verifyReceipt(signature, signingKey, call, inputHash, outputHash) => booleanVerifies the signature.
generateEncryptionKeyPair() => { secretKey, publicKey }A fresh X25519 key pair.
encryptionPublicKey(secretKey) => Uint8ArrayThe X25519 public key of a secret.
signingPublicKey(seed) => Uint8ArrayThe Ed25519 public key of a seed.
sha256, randomBytesSHA-256 and random bytes.
toHex, fromHex, toBase64, fromBase64, utf8Encodings.
WEIGHTS_CIPHER'xchacha20poly1305-64k-v1'The cipher id.
WEIGHTS_CHUNK_BYTES65536The plaintext chunk size.
WeightsCipherHeadertype{ cipher, noncePrefix: Uint8Array, plaintextBytes: number, chunkBytes }
SealedWeightstypeWhat sealWeights returns: { key: Uint8Array, header: WeightsCipherHeader, ciphertext: Uint8Array, sha256: Uint8Array }

The byte layouts are in Sealed models, Grants and Calls and receipts.

voynich/program#

ExportWhat it is
PROGRAM_IDThe address of the voynich program the SDK is built for, as a PublicKey.
ATTESTATION_PROGRAM_IDThe address of the attestation program in the SDK's IDL. The client reads the one in force from the chain's Config.
addresses(programId?, attestationProgramId?)The PDAs: config, model(name), enclave(signingKey), grant(model, enclave), call(caller, nonce), receipt(call), record(signingKey). Keys are PublicKey or base58 strings; nonce is a bigint.
pda(programId, ...seeds)A PDA from raw seeds.
eventAccounts(programId){ eventAuthority, program }, the two accounts every instruction ends with.
chainPrograms(connection, ids?)Typed Anchor program clients, { voynich, attest }, for reading accounts and decoding events.
decodeAttestation(data)Decodes an attestation record of layout version 1 into { layoutVersion, signingKey, hardwareType, measurement, recordedSlot, expiresAtSlot, reportSlot }.
decodeWeightsHeader(data)Decodes the 56-byte header of a Weights account into { model, index, sizeBytes, writtenBytes }.
BNAnchor's big-number class.
Voynich, AttestThe IDL types.

The accounts and instructions themselves are in the Program reference.

Errors#

The client throws a VoynichError:

FieldMeaning
codestring

What went wrong. One of the codes below, or the code of a failed call.

messagestring

A sentence to show.

callCall, optional

The call, when the error happened after its price was in escrow.

refundStatestring, optional

With call: unavailable, pending-deadline, refundable or refunded.

CodeRaised byWhen
WALLET_REQUIREDevery write, account()The client has no signer.
PROGRAM_MISMATCHcall, grant, verifyThe API names a program other than PROGRAM_ID.
INVALID_CHAIN_ACCOUNTcall, grantThe Config, Model or Enclave is missing on chain or not owned by the program.
MODEL_MISMATCHcall, grantThe accounts on chain are not the model and enclave asked for.
MODEL_NOT_LIVEcall, grantThe model is not in a status that allows the action.
OWNER_REQUIREDgrantThe signer is not the model's owner.
INVALID_ATTESTATIONcall, grantThe enclave's record does not hold: address, owner, layout, key, expiry or measurement.
GRANT_REQUIREDcallThe enclave has no active grant for the model on chain.
ENCLAVE_UNAVAILABLEcallNo live, reachable enclave holds a live grant for the model, or the enclave named in options.enclave is not one.
ENCLAVE_MISMATCHcall, grantThe API answered with another enclave than the one asked for.
CALL_FAILEDcallThe call did not settle and the API gave no code of its own.
INVALID_ANSWERcallThe answer is incomplete.
RECEIPT_MISMATCHcallThe answer or the receipt belongs to another call.
VERIFICATION_FAILEDcallA check on the receipt failed.
CALL_INTERRUPTEDcallThe call was interrupted after escrow by something other than the API.
MODEL_TOO_LARGEsealThe ciphertext needs more than 8 Weights accounts.
CREATE_MODEL_TOO_LARGEsealThe quote's canCreate is not true: the create_model transaction is larger than 1,104 bytes or the stored manifest larger than 4,096.
CONFIGURATION_REQUIREDsealThe API does not name the program.
ALLOCATION_FAILEDsealCreating a Weights account failed.
INVALID_WEIGHTSsealA Weights account does not match the model.
RESUME_MISMATCHsealThe saved state does not match the model on chain.
TRANSACTION_FAILEDevery writeA transaction was refused. The message carries the reason.
TRANSACTION_EXPIREDevery writeA transaction's blockhash expired before it landed.
TRANSACTION_NOT_SUBMITTEDevery writeThe API reports the transaction as built, not submitted.

A request the API refuses is thrown as an ApiClientError from @voynich/contract, with status (the HTTP status), code and body.error. The codes are in HTTP API: Overview. After a call's price is in escrow, call wraps an API error in a VoynichError with the same code.

preprocessSketch and the functions of voynich/crypto throw a plain Error for an input of the wrong shape or length, and decryption throws when a ciphertext does not authenticate.