Getting started

Core concepts

Five objects. Everything in SwiftProof is built from these.

Chain

A chain is a sequence of events that must happen in a defined order. You create a chain once per operation — one delivery, one site visit, one document handoff. The chain tracks the entire lifecycle from start to finish and produces a tamper-proof audit trail when complete.

A chain has a status of open until every actor confirms their step. Once all steps are confirmed it becomes completed. If a link expires before the actor confirms, the step is marked expired and the chain becomes failed.

Handoff

A handoff is one step inside a chain — a single event that a specific actor must confirm. When you create a chain you define an ordered list of handoffs. Each handoff gets a unique one-time confirmation_url that you send to the responsible actor.

When the actor opens the confirmation link, SwiftProof captures their GPS coordinates, device timestamp, and a cryptographic signature. That data becomes a permanent, tamper-evident record attached to the handoff.

Actor

An actor is the person or system responsible for confirming a handoff. You identify actors by name when creating a chain — "Kitchen — Surulere", "Rider — Emeka", "Site Inspector". SwiftProof does not require actors to have accounts. They confirm via a link in any mobile browser.

Confirmation link

A confirmation link is a one-time URL sent to an actor so they can confirm their handoff. The link opens a lightweight mobile-optimised page. The actor taps confirm, the page captures GPS and timestamp, and the handoff is sealed. The link cannot be used again.

Links expire after 48 hours by default. Expiry is configurable per chain at creation time.

Audit trail

The audit trail is the complete verified record of all confirmed handoffs in a chain. Each entry contains the event name, actor, GPS location, confirmed timestamp, and a validity flag. The trail is cryptographically signed — any tampering with the underlying data is detectable via chains.verify().

Order matters. Handoffs must be confirmed in the order they were defined. An actor cannot confirm a later step until earlier steps are complete. This prevents back-dating or skipping steps.

How they fit together

You create one chain per operation. The chain contains ordered handoffs, each assigned to an actor. You distribute confirmation links to each actor. When all actors confirm, the chain produces a signed audit trail you can verify at any time.