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
pip install verdockimport verdock exposes __version__, PolicyError, Refused and guard. Import the other modules directly.
verdock.policy#
| Name | Purpose |
|---|---|
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.
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#
| Name | Purpose |
|---|---|
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.
| Method | Purpose |
|---|---|
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#
| Module | Main names | Documented in |
|---|---|---|
verdock.maker_checker | MakerCheckerStore, check_evidence | Maker and checker |
verdock.manifest | issue, key_id, ManifestRegistry, ManifestError, verify_chain | Limits and manifests |
verdock.disclosure | disclose, verify_disclosure | Selective disclosure |
verdock.exchange | ExchangeStore, SendPolicy, verify_exchange_receipt | Authorized exchange |
verdock.exceptions | exceptions(outcome_log=None, held_queues=(), older_than_minutes=15, now=None) | Held queue and exceptions |
verdock.queue | HeldQueue with hold, get, held, close | Held queue and exceptions |
verdock.egress | EgressGateway, allowed_hosts | Limits and manifests |
verdock.adapters | StripeAdapter, RazorpayAdapter, load_env | Stripe, Razorpay |
Amounts are integers in minor units everywhere. Refused is raised when a call is refused and PolicyError when a policy is invalid.