TallwrightDocs

Quickstart: your first proof

From an Environment to an exhibit you have checked yourself, offline, in Python. The three blocks that record, take the exhibit and check it are the ones the product's tests run as printed, against a real door and a real exhibit.

What you need

  • An Environment in the backoffice, and its two values: the ingest address, and the key, which is shown once, when the Environment is made. Keep the key in your secret store, out of your code and out of your logs.
  • Python 3.11, 3.12 or 3.13.
  • The SDK, tallwright-cloud, in the process where your agent acts.

    Not public yet. The package is not on an index, so there is no line to install it with; this page will carry that line the day it is.

  • The verifier, evidence-verify. The Verifier screen of the backoffice says how to get it.

In the shell you run the examples from:

export TALLWRIGHT_INGEST='<the ingest address the backoffice shows>'
export TALLWRIGHT_KEY='<the key of the Environment>'

In PowerShell:

$env:TALLWRIGHT_INGEST = '<the ingest address the backoffice shows>'
$env:TALLWRIGHT_KEY = '<the key of the Environment>'

1. Record one action

import os
from tallwright_cloud import Tallwright

client = Tallwright(os.environ["TALLWRIGHT_INGEST"], os.environ["TALLWRIGHT_KEY"], "./tallwright-evidence")
captured = client.capture("Refund of 120 EUR approved for ticket 8812", action_type="refund.approved")
print(captured.record_id, captured.receipt.status, captured.receipt.leaf_index)

capture commits to the content, keeps the evidence, sends the line and waits for the door's receipt. ./tallwright-evidence/<record_id>/ now holds disclosure.json (your content and its salt), line.json (what was sent) and receipt.json (what the door answered). That folder is the only place your content exists for Cloud Proof: keep it the way you keep the records it describes, and never send it to us.

The receipt is a confirmation, not a proof. The proof is the exhibit, once a witness has covered the record at the next anchor run. The first record of a new Environment asks for one at once.

2. Get the exhibit

With an export key, made for the Environment on the Environments screen and shown once, the SDK takes the exhibit of one record. Set TALLWRIGHT_EXHIBITS to the exhibit address shown with the key, TALLWRIGHT_EXPORT_KEY to the key, and RECORD_ID to the name step 1 printed:

import os
from tallwright_cloud import Exhibits

exhibits = Exhibits(os.environ["TALLWRIGHT_EXHIBITS"], os.environ["TALLWRIGHT_EXPORT_KEY"], "./tallwright-evidence")
print(exhibits.save(os.environ["RECORD_ID"]))

It files evidence.json, policy.json and our-claims.json under <record_id>/exhibit/. ExhibitNotReady means no witness has covered the record yet: ask again after the next anchor run. Without an export key, the Exhibits screen of the backoffice gives a link that opens once, and client.save_exhibit(link) files the same three files in the same place.

3. Check it yourself, offline

In the record's folder:

evidence-verify exhibit/evidence.json --policy exhibit/policy.json --disclosure disclosure.json
python -c "import json; p = json.load(open('exhibit/policy.json')); c = json.load(open('exhibit/our-claims.json')); p['as_of'], p['tsa_anchor'] = c['as_of']['value'], c['tsa_anchor']['value']; json.dump(p, open('accepted.json', 'w'))"
evidence-verify exhibit/evidence.json --policy accepted.json --disclosure disclosure.json
python -c "import base64, json; d = json.load(open('disclosure.json')); p = bytearray(base64.b64decode(d['payload_b64'])); p[0] ^= 1; d['payload_b64'] = base64.b64encode(p).decode(); json.dump(d, open('changed.json', 'w'))"
evidence-verify exhibit/evidence.json --policy accepted.json --disclosure changed.json

The first check exits 3: the record's integrity is verified, and the time is left for you to accept. The third exits 0, once you accept the two values the exhibit asks you to take on Tallwright's word. The last exits 1: the fourth line changes one bit of your content, whatever it says, and one changed byte of the content is a disclosure the sealed record contradicts. What each answer rests on, and why the first one stops where it does, is step 6 of Cloud Proof over HTTP.

Next

  • Not waiting on the network. client.submit returns once the evidence is safe and sends in the background; two ways to record.
  • Evidence that outlives the process, on a volume or in a bucket: evidence stores.
  • One Environment per end customer: many end customers.
  • When an answer does not come, and why a retry loop of your own is the wrong fix: pending and resend.