# 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="/files/EetrHLrOAEjFWiJAhhjU" 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gotproof.xyz/implementation-guide.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.