> For the complete documentation index, see [llms.txt](https://docs.gotproof.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotproof.xyz/technical-architecture.md).

# Technical Architecture

This page describes how $PROOF turns real-world actions into **verifiable on-chain anchors**.

It’s Solana-first. It’s built for **high volume** and **fast auditability**.

<figure><img src="https://3069195333-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvPzgXEMNpAWMLYXanq7T%2Fuploads%2FkuC724R8OOc4HrkVbhH5%2FUntitled%20design%20(13).gif?alt=media&amp;token=762f469d-ce2e-46e5-8f51-f46b041d3bbe" alt=""><figcaption></figcaption></figure>

### System layers (mental model)

* **Execution Layer**: collects intent, does batching, optional conversion routing.
* **Verification Layer**: produces commitments and anchors them on-chain.
* **Integration Layer**: APIs, webhooks, and platform connectors (100+ integrations).

{% hint style="info" %}
The core invariant: **off-chain context** → **commitment** → **on-chain anchor** → **auditable reference**.
{% endhint %}

### Chain + verification model

#### Primary chain

* **Solana mainnet** for throughput and low latency.
* Anchors are referenced by **transaction signature**.

#### What “Proof-of-History” means here

Solana uses **PoH** as a verifiable time source.\
Finality and ordering come from Solana’s **PoS + Tower BFT** consensus.

#### Anchor contents (minimum)

Every verification should be able to point to:

* `txSignature` (the anchor)
* a `commitment` (hash or Merkle root)
* optional: program/account references for richer proofs

<details>

<summary>Why commitments exist</summary>

Blockchains are good at **immutability**, not storing large receipts.

So you store a small commitment on-chain.\
You store rich metadata off-chain.\
You prove linkage by re-hashing the metadata and matching the commitment.

</details>

### Data flow (end-to-end)

#### 1) User / system initiates an event

Examples:

* creator donation
* invoice payment
* payroll line
* reserve snapshot

**Inputs** typically include:

* `amount` + `asset` (and optional fiat conversion context)
* subject identifiers (platform payout ID, invoice ID, asset ID)
* metadata blob (receipt bundle, line items, memo, policy tags)

#### 2) Build a commitment

Two common patterns:

* **Single event hash**: `sha256(metadataBlob)`
* **Batch Merkle root**: `root(sha256(item1), sha256(item2), …)`

{% code title="commitment-examples.txt" %}

```
single: sha256(metadata_json)
batch:  merkle_root([sha256(item_0), sha256(item_1), ...])
```

{% endcode %}

#### 3) Anchor on-chain (Solana)

<div align="left"><figure><img src="https://3069195333-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvPzgXEMNpAWMLYXanq7T%2Fuploads%2FuOiT8gngQB1pUGLUgkrN%2FUntitled%20design%20(11).gif?alt=media&amp;token=7b110535-6adc-42e8-adba-4a6c338c6377" alt="" width="344"><figcaption></figcaption></figure></div>

The system submits a transaction that commits to the event/batch.

What an auditor should be able to get from the chain:

* signature exists
* transaction succeeded (`meta.err == null`)
* transaction is finalized (per policy)

#### 4) Publish an audit reference

Typical outputs:

* a public URL to the verification object
* a transaction signature
* optional broadcast to public channels (e.g., X)

#### 5) Observe in a dashboard

Dashboards should be **derived** from:

* on-chain anchors
* the metadata store
* your internal event IDs (for dedupe and reconciliation)

### Developer verification recipes

#### Check finality (Solana RPC)

{% code title="getSignatureStatuses (cURL)" %}

```bash
curl https://api.mainnet-beta.solana.com \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"getSignatureStatuses",
    "params":[["<TX_SIGNATURE>"], {"searchTransactionHistory": true}]
  }'
```

{% endcode %}

{% hint style="success" %}
**Pass condition:** `confirmationStatus` is `finalized` (or your chosen threshold).
{% endhint %}

#### Fetch and validate a transaction succeeded (Node.js)

{% code title="audit-anchor.ts" %}

```ts
import { Connection, clusterApiUrl } from "@solana/web3.js";

const connection = new Connection(clusterApiUrl("mainnet-beta"), "confirmed");

export async function auditAnchor(signature: string) {
  const tx = await connection.getParsedTransaction(signature, {
    maxSupportedTransactionVersion: 0
  });

  if (!tx) throw new Error("Transaction not found (or pruned).");
  if (tx.meta?.err) throw new Error(`Transaction failed: ${JSON.stringify(tx.meta.err)}`);

  return {
    slot: tx.slot,
    blockTime: tx.blockTime,
    feeLamports: tx.meta?.fee
  };
}
```

{% endcode %}

#### Wallet connectivity (Solana-first)

Users typically connect via Solana wallets:

* Phantom
* Solflare
* Backpack

{% hint style="info" %}
If you later support EVM rails, document them separately as a multi-chain adapter. Avoid mixing Solana wallets with EVM wallet examples in the same flow.
{% endhint %}

### Security model

#### What you get “for free”

* **Immutability** of anchors once finalized.
* **Public verifiability** of signatures and confirmations.

#### What you must specify

* **Scope**: which accounts/programs count as “official” anchors.
* **Metadata integrity**: how metadata is hashed and canonicalized.
* **Key management**: who can publish anchors and with what controls.

#### Enterprise controls

* **Multisig** for high-value treasury operations.
* **Role separation** between execution (payout) and verification (anchor).

#### “No trusted setup”

Hash/Merkle commitments do not require trusted setup.\
You rely on Solana’s consensus security for finality and ordering.

### What’s intentionally unspecified (for now)

Some details depend on the production program design:

* program IDs
* account layouts (PDAs)
* exact metadata schemas

Publish those and we can upgrade this page with **program-level decoding** and **strict verification rules**.