[ 08 ] Reference

SDK reference

Both reference SDKs implement the identical Phase 1 core surface — signing, envelopes, authority evaluation, the task state machine, and object builders — module for module. The TypeScript SDK has zero runtime dependencies; the Python SDK targets Python ≥ 3.10.

pip install vact-p-sdknpm install @vact-p-protocol/sdk

crypto

Ed25519 keypairs, JCS + Ed25519 signing and verification (spec §9.2).

Python
Keypair, sign_object, verify_object, verify_signatures, add_signature, digest_object, signing_bytes
TypeScript
Keypair, signObject, verifyObject, verifySignatures, addSignature, digestObject, signingBytes, ALG, PROOF_TYPE

envelope

Builds and validates the universal message envelope: required fields, modes, replay defense (spec §10).

Python
make_envelope, validate_envelope, ReplayCache
TypeScript
makeEnvelope, validateEnvelope, ReplayCache, MODES, VACT_P_VERSION, REQUIRED_FIELDS

authority

Effective-authority intersection, authorization decisions, chain verification (spec §11).

Python
authorize, verify_chain, selector_covers, Decision, EffectiveAuthority
TypeScript
authorize, verifyChain, selectorCovers, selectorsSubset, compareAmounts, enforce, APPROVAL_ORDER, Decision, EffectiveAuthority

objects

Constructors for Passports, Mandates, Delegations, Offers, Quotes, Contracts, Receipts, and Revocations.

Python
make_passport, make_mandate, make_delegation, make_offer, make_quote, make_contract, make_receipt, make_revocation, make_transition, make_error, sign_contract
TypeScript
makeMandate, makeDelegation, makeReceipt, makeRevocation, makeTransition, RECEIPT_TYPES

statemachine

The 17-state task lifecycle and transition validation (spec §15).

Python
STATES, TERMINAL_STATES, TRANSITIONS, validate_transition
TypeScript
STATES, TRANSITIONS, validateTransition, TaskState

ids

URN identifiers, base64url encoding, SHA-256 digests, and RFC 3339 timestamps.

Python
new_id, new_nonce, sha256_urn, b64url, b64url_decode, iso_now, iso_in
TypeScript
newId, newNonce, sha256Urn, b64url, b64urlDecode, isoNow, isoIn, parseIso

jcs

JSON Canonicalization Scheme (RFC 8785) — both SDKs produce byte-identical output.

Python
canonicalize
TypeScript
canonicalize

errors

Typed protocol errors and the shared reason-code registry (spec Appendix B).

Python
VactError, SignatureError, ChainError, StateError, ReplayError, REASON_CODES
TypeScript
— (thrown as standard Error subtypes; reason codes shared with the wire format)

Conformance enforcement

Per spec §31.1, both SDKs enforce:

  • Signing — RFC 8785 JCS canonicalization + Ed25519, top-level proof (§9.2)
  • Envelope — required fields, expiry, nonce, replay defense (§9.5, §10)
  • Authority — effective-authority intersection; delegation can never expand actions, resources, time, budget, or depth; fails closed (§11)
  • State machine — the 17 task states with transition validation (§15)
  • Receipts — execution / policy / evaluation / settlement / revocation builders (§21)
  • Revocation — objects and priority semantics; indeterminate ⇒ deny for material actions (§24)
Test vectors

spec/test-vectors/ contains signed objects generated by the Python SDK and independently verified by the TypeScript test suite, proving both implementations produce byte-identical canonical forms. Regenerate them with make vectors.

Previous← Reference gateway