> ## Documentation Index
> Fetch the complete documentation index at: https://heyaven09.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Attestation Contract: Permanent Proof of Work

> Mints immutable on-chain records for every verified, paid work session on Stellar — giving workers a portable, cryptographically-proven work history.

The attestation contract is the immutable record-keeper of Aven. Every verified, paid work session produces an `AttestationRecord` stored permanently on the Stellar ledger. You cannot fake an attestation — the contract enforces that only the stream contract (set at initialization time) can call `mint_attestation`, which means every record is backed by a real token transfer that happened in the same transaction.

## Contract Address

**Testnet:** `CD22NZLAI53Y2LZB2GNLVITQXZWGZ3AQ6QKVKNUDKWABIIQIDEFSPQCG`

## Key Functions

<ResponseField name="init" type="function → ()">
  Initializes the attestation contract. Must be called once before any other function. The `stream_contract` address set here is the only address ever permitted to call `mint_attestation`.

  **Parameters:**

  * `admin` — Admin address for the contract
  * `stream_contract` — The authorized stream contract address
</ResponseField>

<ResponseField name="mint_attestation" type="function → u64">
  Creates a new `AttestationRecord` and stores it permanently on the Stellar ledger. Returns the new `attestation_id`.

  This function can **only be called by the stream contract**. It is invoked automatically as part of the `withdraw_approved` or `finalize_checkpoint` execution path — never directly by end users. Both the token transfer and this call occur in the same Stellar transaction, guaranteeing atomicity.

  **Parameters:**

  * `caller` — Must be the registered stream contract address
  * `kind` — Attestation type: `Checkpoint`, `WorkSession`, or `LegacyReviewed`
  * `stream_id` — Stream that generated this attestation
  * `request_id` — Work session / withdrawal request ID; empty string for checkpoint-type attestations
  * `checkpoint_index` — Zero-based checkpoint index; `0` for work-session and legacy types
  * `sender` — Client's Stellar address
  * `recipient` — Worker's Stellar address
  * `amount_paid` — Amount paid in stroops
  * `asset` — Token contract address
  * `category` — Work category inherited from the stream
  * `title` — Stream title copied to the record
  * `period_start_ledger` — Start of the work period in ledger sequence
  * `period_end_ledger` — End of the work period in ledger sequence
  * `active_duration_seconds` — Active working seconds measured during the session; `0` for checkpoint types
  * `client_confirmed` — `true` if the client explicitly approved; `false` for auto-released
  * `auto_released` — `true` if the deadline passed without client action
  * `verifier` — Verifier address for `WorkSession` kind; `None` otherwise
  * `report_hash` — SHA-256 hash of the verification report; `None` otherwise
</ResponseField>

<ResponseField name="get_attestation" type="function → AttestationRecord">
  Returns a single `AttestationRecord` by its ID. Extends the record's TTL on every read.

  **Parameters:**

  * `attestation_id` — The unique attestation identifier
</ResponseField>

<ResponseField name="get_recipient_attestations" type="function → Vec<u64>">
  Returns the list of attestation IDs associated with the given worker address, in the order they were minted. Used by the reputation contract to compute scores.

  **Parameters:**

  * `recipient` — Worker's Stellar address
</ResponseField>

<ResponseField name="get_sender_attestations" type="function → Vec<u64>">
  Returns the list of attestation IDs associated with the given client address, in the order they were minted.

  **Parameters:**

  * `sender` — Client's Stellar address
</ResponseField>

<ResponseField name="verify_attestation" type="function → bool">
  Returns `true` if the attestation exists and has a positive `amount_paid`. A lightweight existence check that does not return the full record.

  **Parameters:**

  * `attestation_id` — The attestation ID to check
</ResponseField>

## AttestationRecord Fields

Every `AttestationRecord` is stored in Soroban's persistent storage and contains the full context of the verified work event.

<ResponseField name="id" type="u64">
  Unique auto-incrementing identifier assigned at mint time.
</ResponseField>

<ResponseField name="kind" type="AttestationKind">
  The minting path that produced this record. See [AttestationKind Values](#attestationkind-values) below.
</ResponseField>

<ResponseField name="stream_id" type="u64">
  The ID of the stream this attestation belongs to.
</ResponseField>

<ResponseField name="request_id" type="String">
  The work session or withdrawal request ID. Empty string for `Checkpoint`-kind attestations.
</ResponseField>

<ResponseField name="checkpoint_index" type="u32">
  Zero-based checkpoint index for `Checkpoint`-kind attestations. `0` for `WorkSession` and `LegacyReviewed` kinds.
</ResponseField>

<ResponseField name="sender" type="Address">
  The client's Stellar address.
</ResponseField>

<ResponseField name="recipient" type="Address">
  The worker's Stellar address — the subject of the attestation.
</ResponseField>

<ResponseField name="amount_paid" type="i128">
  Amount paid to the worker in stroops. Always greater than zero.
</ResponseField>

<ResponseField name="asset" type="Address">
  Token contract address of the payment asset (USDC or XLM).
</ResponseField>

<ResponseField name="category" type="Category">
  Work category inherited from the parent stream: `Freelance`, `Salary`, `Bounty`, `Grant`, `AgentTask`, or `Subscription`.
</ResponseField>

<ResponseField name="title" type="String">
  Human-readable title copied from the stream at mint time.
</ResponseField>

<ResponseField name="period_start_ledger" type="u32">
  Stellar ledger sequence marking the start of the work period.
</ResponseField>

<ResponseField name="period_end_ledger" type="u32">
  Stellar ledger sequence marking the end of the work period.
</ResponseField>

<ResponseField name="active_duration_seconds" type="u64">
  Active working seconds measured and submitted for the session. `0` for `Checkpoint` and `LegacyReviewed` kinds.
</ResponseField>

<ResponseField name="minted_at_ledger" type="u32">
  Stellar ledger sequence at which this attestation was minted. Used by the reputation contract for recency weighting.
</ResponseField>

<ResponseField name="client_confirmed" type="bool">
  `true` when the client explicitly called `approve_withdrawal` or `approve_checkpoint`. `false` when the deadline elapsed and the request auto-released.
</ResponseField>

<ResponseField name="auto_released" type="bool">
  `true` when the withdrawal auto-released after the approval timeout without explicit client action.
</ResponseField>

<ResponseField name="verifier" type="Option<Address>">
  The verifier address that signed off on the session. Present only for `WorkSession`-kind attestations; `None` for other kinds.
</ResponseField>

<ResponseField name="report_hash" type="Option<BytesN<32>>">
  SHA-256 hash of the verification report uploaded to the dashboard. Present only for `WorkSession`-kind attestations; `None` otherwise.
</ResponseField>

## AttestationKind Values

The `kind` field describes how the attestation was created.

| Kind             | Description                                                                                                              |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `Checkpoint`     | Minted when a stream checkpoint period is finalized — either by explicit client approval or by the auto-approval timeout |
| `WorkSession`    | Minted via the verifier-backed path: the Aven dashboard verifier validated a CLI session report before payout            |
| `LegacyReviewed` | Minted via the direct `request_withdrawal` path when no verifier is configured on the stream contract                    |

<Note>
  The `kind` field tells you how much trust to place in an attestation. A `WorkSession` attestation has a cryptographic evidence hash and a named verifier attached. A `LegacyReviewed` attestation relies on the client's manual review of the withdrawal request.
</Note>

## Minting Event

Every successful `mint_attestation` call emits an `attestation_minted` event on the Stellar ledger. You can subscribe to this event from any Stellar RPC endpoint to build real-time integrations.

**Topics (indexed):**

* `attestation_id` — The new attestation ID
* `stream_id` — The parent stream ID
* `checkpoint_index` — Zero-based checkpoint index (or `0` for work-session types)

**Data (non-indexed):**

* `recipient` — Worker's Stellar address
* `amount_paid` — Amount paid in stroops
* `kind` — `Checkpoint`, `WorkSession`, or `LegacyReviewed`
* `client_confirmed` — Whether the client explicitly approved
* `auto_released` — Whether it was released after timeout

## Authorization

Only the stream contract address registered during `init` may call `mint_attestation`. Any other caller receives an `Unauthorized` error (code 3). This design ensures that:

1. Every attestation on the ledger corresponds to a real token payment.
2. No third party can forge attestations or inflate a worker's reputation.
3. The stream contract's atomicity guarantee extends to the attestation layer — payment and record creation are inseparable.