> 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/implementation-guide.md).

# Implementation Guide

This page is for **builders** integrating $PROOF into a product or workflow.

It focuses on two tasks:

* **Create** verifications (payments / ownership / reserves).
* **Audit** verifications (reproduce commitments and validate on-chain anchors).

{% hint style="info" %}
If you only need the mental model first, read [Technical Architecture](/technical-architecture.md) and [Core Capabilities](/core-capabilities.md).
{% endhint %}

### Prerequisites

* A **Solana RPC endpoint** (mainnet + optional devnet).
* A wallet + signer for publishing anchors (server key or multisig).
* A place to store verification metadata (object storage, DB, or both).

{% hint style="warning" %}
Define canonicalization rules before hashing metadata.\
If two systems serialize JSON differently, hashes won’t match.
{% endhint %}

### Integration modes

#### Mode A — No-code / dashboard

Best for pilots.

1. Visit `gotproof.xyz`.
2. Connect a Solana wallet (Phantom / Solflare / Backpack).
3. Create verification events via UI.
4. Copy the `txSignature` + public proof URL for audit sharing.

#### Mode B — Platform integration (API + webhooks)

Best for production.

You typically implement:

* `POST /verifications` (create)
* `GET /verifications/:id` (fetch)
* `POST /webhooks` (receive events like `anchored`, `finalized`)

{% hint style="info" %}
Exact endpoints and auth depend on your deployment and product tier.\
This guide documents the **flow** and **verification logic**.
{% endhint %}

### Reference flow (create → anchor → verify)

{% stepper %}
{% step %}

### 1) Build metadata (the thing you want to prove)

Examples:

* donation receipt bundle + platform payout ID
* payroll batch register
* reserve snapshot (list of accounts + balances + timestamp)

Minimum fields to include:

* stable identifiers (`subject.type`, `subject.id`)
* amounts (`asset`, `quantity`, optional fiat context)
* timestamps (ISO 8601)
* any external references (invoice IDs, payout IDs, etc.)
  {% endstep %}

{% step %}

### 2) Compute a commitment

Use either:

* **Single proof hash**: `sha256(metadataBlob)`
* **Batch root**: Merkle root over per-item leaf hashes

Persist:

* the commitment value
* the exact metadata blob used to produce it
  {% endstep %}

{% step %}

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

Submit a Solana transaction that commits to the hash/root.

At minimum you need to retain:

* `txSignature`
* commitment value
* network (`mainnet-beta`, `devnet`)
  {% endstep %}

{% step %}

### 4) Verify (auditor / support / customer success)

Verification checks:

1. **Transaction exists**
2. **Transaction succeeded**
3. **Transaction is finalized** (per your policy)
4. **Commitment matches** the published metadata
   {% endstep %}
   {% endstepper %}

### Solana: verification snippets

#### Check finality (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 %}

#### Fetch a transaction and ensure it succeeded (Node.js)

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

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

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

export async function verifyAnchor(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
  };
}
```

{% endcode %}

{% hint style="warning" %}
If anchors live in a dedicated Solana program, add **program ID checks** and **account decoding** once published.
{% endhint %}

### Webhooks (recommended)

Use webhooks to avoid polling and to separate concerns:

* your system emits the event (payment/payroll/ownership/snapshot)
* $PROOF emits the state transition (anchored → confirmed → finalized)

Suggested events:

* `verification.created`
* `verification.anchored` (has `txSignature`)
* `verification.finalized`
* `verification.failed` (include reason)

{% hint style="info" %}
Always design webhook handlers to be **idempotent**.\
Expect retries and out-of-order delivery.
{% endhint %}

### Pseudocode (legacy)

The diagram below is a conceptual sketch of the integration path.

<figure><img src="https://3069195333-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvPzgXEMNpAWMLYXanq7T%2Fuploads%2FVPviSYmbgn11qV3PA8gI%2Fimage.png?alt=media&amp;token=1ba63d4e-f751-4ae9-9990-bc737fee5e64" alt=""><figcaption><p>Illustrative integration pseudocode.</p></figcaption></figure>

### Token utility (tiers)

Use tiers as **feature gates**, not as vague marketing.

* **1M $PROOF**: tier unlock (feature set depends on product policy)
* **5M $PROOF**: higher tier unlock
* **10M $PROOF**: highest tier unlock (often “DAO / enterprise” tier)

{% hint style="info" %}
Publish a tier → feature matrix somewhere.\
This page only documents how tiers are used operationally.
{% endhint %}

### Revenue share (if applicable)

If you advertise revenue share:

* specify **who** receives it (holders, stakers, LPs)
* specify **how** it’s calculated (basis, cadence, exclusions)
* link to on-chain references (distribution txs) when possible

Avoid one-off numbers without context.