Snapshots

A Snapshot is Uhpenry's source of truth for a user's history on a specific project. It is a persistent container that stores the user and owner identities, the Snapgate used to access the project, and every Snapcharge (transactional event) that ever occurred through that gate.

What a Snapshot is

• A container of records: includes the serialized Snapgate and the serialized list of all Snapcharges tied to that gate.
• A tamper-evident audit trail: each Snapcharge embeds its own cryptographic verification data (integrity & signer). The Snapshot aggregates those proofs for end‑to‑end auditability.
• Persistent by design: Snapshots cannot be deleted. They are updated only when a new Snapcharge completes.

What a Snapshot is not

• Not a payment processor. Payments/updates happen via Snapcharge.
• Not an access switch. Enforcement (revoke/suspend) is handled at the Snapgate and reflected in subsequent Snapcharges.
• Not a mutable ledger. There is no API to rewrite or retroactively edit prior state.

Core Guarantees

1. Persistence: Snapshots are never deleted.
2. Controlled Mutability: The only way a Snapshot changes is when a new Snapcharge is added.
3. Reconstructability: You can reproduce the exact project state (structure, license, price, policies) as it existed at any past access event.
4. Verifiability: Each Snapcharge carries cryptographic proofs so anyone can check integrity without trusting Uhpenry's internals.

Lifecycle

1. Initialization

   • When a user first gains access (free or paid), a Snapgate is generated and the first Snapcharge completes.
   • A Snapshot is created the first time a completed Snapcharge needs to be recorded for that user–project pair.

2. Updates

   • Any subsequent access event (e.g., new version, upgrade/downgrade, free update) produces a new Snapcharge.
   • The Snapshot is updated to include the new Snapcharge and the current (serialized) state of the Snapgate.

3. Enforcement Events

   • If the owner revokes/suspends access (via Snapgate), that enforcement is reflected by follow‑up Snapcharges (e.g., status, terms, or access changes) rather than by editing prior entries.

4. Long-term Retention

   • Snapshots remain available indefinitely for audit, disputes, and user assurance.

Data Model (Developer Reference)

Below is a conceptual view of the persisted fields (names reflect current schema; some fields omitted for brevity):

// Snapshots
{
  updatedAt: number,
  Snapcharges: string[],       // JSON-stringified Snapcharge objects (denormalized, frozen)
  Snapgate: string,            // JSON-stringified Snapgate object (denormalized, frozen)

  user: {                      // User summary
    id: Id<'users'>,
    publicId: string,
    name: string,
    username: string,
    email: string,
    image: string,
  },

  owner: {                     // Project owner summary
    id: Id<'users'>,
    publicId: string,
    name: string,
    username: string,
    email: string,
    image: string,
  },

  visibility: 'private' | 'user-owner' | 'public',

  // Easy linking / queries
  SnapgateId: Id<'Snapgates'>,
  boothId: Id<'booths'>,
  productType: 'projects'
  productId?: Id<'projects'>,

  // Optional caller-defined metadata
  metadata?: Record<string, any>,
}

Why serialize (stringify) Snapgate & Snapcharges inside the Snapshot?

To preserve point‑in‑time truth even if canonical tables evolve later. The Snapshot contains a frozen copy of what actually existed (including terms, prices, policies, structure) at each event. This enables deterministic replay and independent verification.

Canonical rows (e.g., in Snapcharges and Snapgates) remain the live source for ongoing operations, while the Snapshot's serialized copies serve as an immutable audit cache.

Visibility & Access Control

visibility: 'private' | 'user-owner' | 'public'

Enforcement actions (revoke/suspend) are executed at the Snapgate and will be reflected by subsequent Snapcharges captured in the Snapshot.

Verification

A Snapshot's integrity is demonstrated by verifying each embedded Snapcharge. Each Snapcharge includes a verifications[] array with integrity and signer entries:

verification := {
  integrity: {
    hash: string,   // deterministic hash of the canonical Snapcharge payload
    token: string,  // signed JWT covering the integrity hash
    kid: string,    // key id used to sign the integrity token
  },
  signer: {
    hash: string,   // deterministic hash over {integrity.hash, integrity.kid, integrity.token}
    token: string,  // signed JWT (signer layer)
    kid: string,    // key id used by signer layer
  },
  createdAt: number,
  reason: 'initial' | 'final' | 'update' | 'refund'
}

Verification Algorithm (High‑level)

1. Load the Snapshot's serialized Snapcharges and parse them.

2. For each Snapcharge:

   • Recompute the deterministic JSON of the Snapcharge payload (field order & normalization must match Uhpenry's published spec).
   • Hash it and compare with verification.integrity.hash.
   • Validate verification.integrity.token using the published public key designated by integrity.kid.
   • Recompute the signer input {integrity.hash, integrity.kid, integrity.token}, hash it, and compare with verification.signer.hash.
   • Validate verification.signer.token using the public key for signer.kid.

3. If all Snapcharges validate, the Snapshot's history is tamper‑evident and consistent.

Uhpenry publishes the public keys and the deterministic‑serialization rules so verification can be performed client‑side or server‑side without contacting Uhpenry.

Reconstructing Past Project State

The Snapshot enables complete replay of the project's state at any time a Snapcharge was recorded.

Outcome: you obtain the exact repository layout, license, and commercial policy that the user agreed to and received at that moment.

Operational Invariants (Important)

• No destructive edits: There is no API to delete or rewrite a Snapshot.
• Append‑only via Snapcharge: Any change to access, pricing, or policy is reflected as a new Snapcharge, never by editing old ones.
• ID consistency: snapshot.SnapgateId must match the Snapgate._id referenced by each Snapcharge's SnapgateId.
• Time ordering: Snapcharges should be displayed by their completedAt (or snapshotCompletedAt) for human‑friendly history; verification does not require wall‑clock order but consistent ordering eases audits.
• Denormalized cache: Snapshots.Snapgate and Snapshots.Snapcharges[] are write‑once (per event). Canonical tables may continue evolving for live operations.

Snapshot Overview Diagram

The diagram below illustrates the core flow of Snapshots in Uhpenry:

• A User and Owner connect through a Snapgate.
• Each access event produces a Snapcharge, which is appended to the Snapshot.
• The Snapshot persists serialized copies of both the Snapgate and Snapcharges.
• From these, the Snapshot guarantees Persistence, Auditability, Reconstructability, and Verifiability.

Snapshots are the immutable source of truth for a user's interactions with a project in Uhpenry. By storing serialized copies of Snapgates and Snapcharges, Snapshots ensure that every access event, license acceptance, and enforcement action is tamper-evident, reconstructable, and verifiable.

They provide a persistent, append-only audit trail, allowing both users and owners to replay project states at any point in time, validate integrity cryptographically, and resolve disputes or verify compliance. Snapshots do not process payments or grant access directly they capture the outcomes and states managed by Snapgate and Snapcharge, creating a comprehensive historical record that is both trustworthy and auditable.

In essence, Snapshots guarantee that every user‑project interaction is preserved faithfully, enabling Uhpenry to offer secure, transparent, and verifiable project histories.

Note: This guide is living documentation. We welcome contributions and corrections via GitHub or support@uhpenry.com.