VERDOCK

Python API

The importable modules of the verdock package, version 0.3.0, with the signatures and behaviour taken from the source. Standard library only.

On this page
Terminal
pip install verdock

import verdock exposes __version__, PolicyError, Refused and guard. Import the other modules directly.

verdock.policy#

NamePurpose
load_policy(path)Read a policy file (.json, or the YAML subset otherwise) and validate it.
loads_policy(text, fmt="yaml")Parse and validate policy text. fmt is "yaml" or "json".
validate_policy(raw)Validate a mapping and return a normalized copy.
policy_hash(policy)SHA256 hex of the canonical JSON form. See the policy file.
decide(policy, operation, amount_minor, currency=None)Returns a Decision with operation, level, allowed, needs_approval, reason, limit_minor and approvers_required.
required_approvers(policy, operation, amount_minor)The quorum for this amount.

verdock.guard#

guard(operation, *, policy_path="verdock.yaml", state_dir=".verdock", reconcile=None) decorates a synchronous function that accepts amount_minor, currency, counterparty, request_key and request_id.

Python
import verdock

@verdock.guard("payout", reconcile=read_payout_record)
def payout(amount_minor, currency, counterparty, request_key, request_id=None):
    return send_payout(amount_minor, currency, counterparty, request_id)

The guard refuses reused keys, actions that need approval, missing readers, async functions, and calls above the daily team or counterparty caps. It reserves before calling and keeps uncertain reservations. An exception leaves the action UNKNOWN. The guard never retries on its own. Without a reader, it refuses execution. read_payout_record(request_id) returns a record with amount_minor and currency, or None.

verdock.receipts#

NamePurpose
ReceiptLog(path, seed, clock=time.time, bank_salt=None)Append signed receipts to an NDJSON file. One writer per file. .public_key holds the hex key.
ReceiptLog.append(step_id, action_id, params, success, actor=None, extra=None, ts_ms=None, approvals=None)Sign, write and return one line.
verify_log(lines_or_path, trust_anchor_hex, manifest_root=None)Returns a report with ok, count and failures, each failure with a line and a reason.
create_seed(path), load_seed(path)Create and read a private seed file.
canonical_bytes(receipt), line_hash(line)The signed bytes and the chain digest.

verdock.outcome#

OutcomeLog(path) with expect(operation_id, expected, fields, status_field=None, pending_values=()), record(operation_id, state, observed=None), history(operation_id), latest(operation_id) and latest_states(). The states are VERIFIED, MISMATCH, UNKNOWN and PENDING. compare(expected, observed, fields, status_field=None, pending_values=()) returns a state. may_retry(state, retry="safe") is True only for MISMATCH under safe. See outcome checks.

verdock.invariants#

Invariants(path) keeps caps, locks and stable request ids in one SQLite file.

MethodPurpose
reserve(group_id, cap_minor, amount_minor, customer_id, day, per_customer_day_cap_minor=None)Reserve against the group cap and the account and day cap. Returns the reservation id or raises Refused.
commit(reservation_id), release(reservation_id)Settle a reservation.
group_total(group_id)The amount held in a group.
lock(key, owner, ttl_seconds), unlock(key, owner)A lock with an expiry.
request_id(key)The UUID4 stored for the key, created on first use.

Evidence modules#

ModuleMain namesDocumented in
verdock.maker_checkerMakerCheckerStore, check_evidenceMaker and checker
verdock.manifestissue, key_id, ManifestRegistry, ManifestError, verify_chainLimits and manifests
verdock.disclosuredisclose, verify_disclosureSelective disclosure
verdock.exchangeExchangeStore, SendPolicy, verify_exchange_receiptAuthorized exchange
verdock.exceptionsexceptions(outcome_log=None, held_queues=(), older_than_minutes=15, now=None)Held queue and exceptions
verdock.queueHeldQueue with hold, get, held, closeHeld queue and exceptions
verdock.egressEgressGateway, allowed_hostsLimits and manifests
verdock.adaptersStripeAdapter, RazorpayAdapter, load_envStripe, Razorpay

Amounts are integers in minor units everywhere. Refused is raised when a call is refused and PolicyError when a policy is invalid.