Types and errors
voynich#
| Export | Kind | What it is |
|---|---|---|
default | client | In 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) | function | Creates a client. See Install. |
VoynichError | class | The error the client throws. See Errors. |
preprocessSketch(input) | function | Turns a drawing in any accepted form into the 784 numbers a sketch model takes. See call. |
Voynich | type | The client: ReturnType<typeof createVoynich>. |
VoynichOptions | type | The options of createVoynich. |
WalletSigner | type | { publicKey: PublicKey; signTransaction(transaction: VersionedTransaction): Promise<VersionedTransaction> } |
VoynichSigner | type | WalletSigner | Keypair |
CallOptions | type | { signal?: AbortSignal; onStep?: (step: CallStep) => void; enclave?: string } |
CallStep | type | 'encrypting' | 'awaiting-signature' | 'escrowed' | 'answering' | 'verified' |
Verification | type | The result of verify. |
SealOptions, SealResume, SealProgress | types | The options, the saved state and the progress of seal. |
SketchInput | type | readonly number[] | readonly (readonly number[])[] | Float32Array | Float64Array | { strokes: readonly Stroke[]; width: number; height: number } |
Stroke | type | readonly (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.
| Export | Signature | Does |
|---|---|---|
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) => Uint8Array | Decrypts a plaintext range from that ciphertext range, authenticating every chunk first. |
wrapKey | (key, recipientPublicKey) => Uint8Array | Wraps a 32-byte model key to an enclave's encryption key: the 105-byte envelope of a grant. |
unwrapKey | (envelope, recipientSecret) => Uint8Array | Unwraps it. |
encryptCallInput | (plaintext, enclavePublicKey) => Uint8Array | The input envelope of a call. |
decryptCallInput | (envelope, enclaveSecret) => Uint8Array | Opens it. |
encryptCallOutput | (plaintext, callerPublicKey) => Uint8Array | The output envelope of a call. |
decryptCallOutput | (envelope, callerSecret) => Uint8Array | Opens it. |
receiptMessage | (call, inputHash, outputHash) => Uint8Array | The 114 bytes an enclave signs. |
signReceipt | (seed, call, inputHash, outputHash) => Uint8Array | Signs them with an Ed25519 seed. |
verifyReceipt | (signature, signingKey, call, inputHash, outputHash) => boolean | Verifies the signature. |
generateEncryptionKeyPair | () => { secretKey, publicKey } | A fresh X25519 key pair. |
encryptionPublicKey | (secretKey) => Uint8Array | The X25519 public key of a secret. |
signingPublicKey | (seed) => Uint8Array | The Ed25519 public key of a seed. |
sha256, randomBytes | SHA-256 and random bytes. | |
toHex, fromHex, toBase64, fromBase64, utf8 | Encodings. | |
WEIGHTS_CIPHER | 'xchacha20poly1305-64k-v1' | The cipher id. |
WEIGHTS_CHUNK_BYTES | 65536 | The plaintext chunk size. |
WeightsCipherHeader | type | { cipher, noncePrefix: Uint8Array, plaintextBytes: number, chunkBytes } |
SealedWeights | type | What sealWeights returns: { key: Uint8Array, header: WeightsCipherHeader, ciphertext: Uint8Array, sha256: Uint8Array } |
The byte layouts are in Sealed models, Grants and Calls and receipts.
voynich/program#
| Export | What it is |
|---|---|
PROGRAM_ID | The address of the voynich program the SDK is built for, as a PublicKey. |
ATTESTATION_PROGRAM_ID | The 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 }. |
BN | Anchor's big-number class. |
Voynich, Attest | The IDL types. |
The accounts and instructions themselves are in the Program reference.
Errors#
The client throws a VoynichError:
codestringWhat went wrong. One of the codes below, or the code of a failed call.
messagestringA sentence to show.
callCall, optionalThe call, when the error happened after its price was in escrow.
refundStatestring, optionalWith call: unavailable, pending-deadline, refundable or refunded.
| Code | Raised by | When |
|---|---|---|
WALLET_REQUIRED | every write, account() | The client has no signer. |
PROGRAM_MISMATCH | call, grant, verify | The API names a program other than PROGRAM_ID. |
INVALID_CHAIN_ACCOUNT | call, grant | The Config, Model or Enclave is missing on chain or not owned by the program. |
MODEL_MISMATCH | call, grant | The accounts on chain are not the model and enclave asked for. |
MODEL_NOT_LIVE | call, grant | The model is not in a status that allows the action. |
OWNER_REQUIRED | grant | The signer is not the model's owner. |
INVALID_ATTESTATION | call, grant | The enclave's record does not hold: address, owner, layout, key, expiry or measurement. |
GRANT_REQUIRED | call | The enclave has no active grant for the model on chain. |
ENCLAVE_UNAVAILABLE | call | No live, reachable enclave holds a live grant for the model, or the enclave named in options.enclave is not one. |
ENCLAVE_MISMATCH | call, grant | The API answered with another enclave than the one asked for. |
CALL_FAILED | call | The call did not settle and the API gave no code of its own. |
INVALID_ANSWER | call | The answer is incomplete. |
RECEIPT_MISMATCH | call | The answer or the receipt belongs to another call. |
VERIFICATION_FAILED | call | A check on the receipt failed. |
CALL_INTERRUPTED | call | The call was interrupted after escrow by something other than the API. |
MODEL_TOO_LARGE | seal | The ciphertext needs more than 8 Weights accounts. |
CREATE_MODEL_TOO_LARGE | seal | The 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_REQUIRED | seal | The API does not name the program. |
ALLOCATION_FAILED | seal | Creating a Weights account failed. |
INVALID_WEIGHTS | seal | A Weights account does not match the model. |
RESUME_MISMATCH | seal | The saved state does not match the model on chain. |
TRANSACTION_FAILED | every write | A transaction was refused. The message carries the reason. |
TRANSACTION_EXPIRED | every write | A transaction's blockhash expired before it landed. |
TRANSACTION_NOT_SUBMITTED | every write | The 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.