VERDOCK

Quickstart

Install Verdock, run the built in scene, check an action against a policy and verify the signed receipts. Four commands, no account, no network.

On this page

Limits no prompt can change, every action checked against the record, signed receipts anyone can verify. You need Python 3.10 or newer. There are no runtime dependencies.

Install and run#

pip install verdock
verdock init
verdock check refund 3500 --currency USD --counterparty c1
verdock verify .verdock/receipts.ndjson --public-key $(verdock keys)

What each command does:

  1. pip install verdock installs the package, the command line tool and the open source core.
  2. verdock init writes verdock.yaml with a starting policy and creates a signing key under .verdock. It refuses to replace an existing policy.
  3. verdock demo runs actions through the policy and prints each decision. verdock demo --scene all runs every scene with real Ed25519 signatures.
  4. verdock verify checks every signature and the hash chain offline. It needs the public key you trust, shown in the next section.

Check an action and verify the receipt#

Open verdock.yaml and name the operation you want to control. This policy allows a payout up to 5000, asks for approval above 2000, and fixes both daily caps:

YAML
version: 1
operations:
  payout:
    level: Execute within Limits
    max_amount_minor: 5000
    approval_above_minor: 2000
    currency: USD
    retry: never
caps:
  per_customer_per_day_minor: 10000
  team_per_day_minor: 50000
egress:
  allow_hosts: []

Amounts are integer minor units. 3500 is USD 35.00. Check an action and print your public key:

Terminal
verdock check payout 3500 --currency USD --counterparty c1
verdock keys

The check prints needs approval: approval required above threshold, writes a signed receipt to .verdock/receipts.ndjson, reserves no money and executes nothing. Verify the log against your public key:

Terminal
verdock verify .verdock/receipts.ndjson --public-key PUBLIC_KEY_HEX

Exit status is 0 when every line is intact and signed by the key you trust, 1 when a line fails and 2 for a usage or file error.

Use it from code#

from verdock.policy import load_policy, decide

decision = decide(load_policy("verdock.yaml"), "payout", 1500, currency="USD")
print(decision.allowed, decision.needs_approval, decision.reason)

To wrap a real provider call, use the guard. It decides, reserves against the daily caps, sends once with a stable request id, reads the provider record back and signs the outcome:

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)

read_payout_record(request_id) must read the provider record on its own and return amount_minor and currency, or None. The two functions above are your application code. See the Python API for what the guard refuses.

Next#

No internet on the target machine? Follow the offline install. To see the whole path with approvals and receipts, read your first hour.