Signers and ciphers

Orders are signed and payloads sealed on your machine. Signer and Cipher are protocols; the SDK ships WalletSigner (EIP-712) and SealedBoxCipher (libsodium sealed boxes). A default vorq.Client() builds both from VORQ_WALLET_KEY.

SignerCopy Anchor Link

class Signer(Protocol):
    address: str
    def sign_order_v2(self, terms: OrderTerms, ctx: ChainContext) -> str: ...
    def sign_cancel(self, job_id: str, issued_at: int, ctx: ChainContext) -> str: ...
    def sign_payment_authorization(
        self, *, amount: int, job_id: str, expires_at: int, ctx: ChainContext
    ) -> str: ...
    def sign_nonce(self, nonce: str, chain_id: int) -> str: ...

Implement it to keep the wallet key in a KMS, an HSM or a remote signer. Every signature returns a 0x-prefixed hex string. Use a dedicated wallet funded with your inference budget, never a main wallet's key.

CipherCopy Anchor Link

class Cipher(Protocol):
    @property
    def public_key(self) -> str: ...
    def encrypt(self, data: bytes) -> bytes: ...
    def decrypt(self, data: bytes) -> bytes: ...

The client's cipher is the result key: its public_key goes into every sealed envelope, and decrypt opens results.

WalletSignerCopy Anchor Link

signer = vorq.WalletSigner()                 # key from $VORQ_WALLET_KEY
signer = vorq.WalletSigner(private_key)      # explicit 0x hex key
signer = vorq.WalletSigner.generate()        # fresh throwaway wallet

All signatures are 65 bytes, with v in {27, 28} and low s.

A Client built on a WalletSigner without cipher= derives its result key from the wallet: a Curve25519 key seeded by keccak256 of the wallet's signature over the fixed message VORQ-ENC-V1. The same wallet always derives the same key.

SealedBoxCipherCopy Anchor Link

cipher = vorq.SealedBoxCipher()                                  # own key from $VORQ_CIPHER_KEY
box = vorq.SealedBoxCipher(recipient_public_key=peer).encrypt(b"...")  # also needs an own key

Results sealed to one key open only with that key. When you switch between a derived and an explicit key, keep the old one until its jobs have settled.

ChainContextCopy Anchor Link

Returned by await client.chain_context(), read once from GET /evm/chain. Every on-chain signature takes it; there is no default deployment.

The session handshake is signed under the chain id that GET /auth/nonce announces.

EIP-712 typesCopy Anchor Link

Test vectors for these types are in tests/vectors/signing-v3.json.

Order.

• c is the container commitment (below), so the signature binds one exact payload.
• modelId is the catalog's numeric id and slaSecs the window in seconds.
• rateIn and rateOut are scaled integers.
• designated is the provider's registry id, or 0 for an open order.
• expiresAt is now plus the SLA window plus VORQ_SETTLEMENT_MARGIN, capped at 24 hours.
• The job id is not signed; it is keccak256(owner ‖ c).

Payment authorization. from is your address, to is job_registry, value is the quoted amount, validAfter is 0, validBefore is expiresAt + 1, and nonce is the job id, which makes the authorization single-use.

Container formatCopy Anchor Link

container = 0x01 ‖ seed_wrap (80 bytes) ‖ ciphertext
c         = keccak256(0x01 ‖ seed_wrap ‖ keccak256(ciphertext))
job_id    = keccak256(owner ‖ c)
dek       = HKDF-SHA256(ikm = seed, salt = "", info = "vorq-dek" ‖ owner (20 bytes), L = 32)

• seed_wrap is a sealed box over a fresh 32-byte seed, addressed to the chosen provider's key or the coordinator's escrow key.
• ciphertext is the canonical JSON envelope {v: "vorq-env-v1", owner, result_key, input} (plus custom_id when set), encrypted under dek with a libsodium secret box.

Test vectors are in tests/vectors/container-v1.json.