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

# Attestation Contract: Permanent On-Chain Work Proofs

> The Aven Attestation Contract mints tamper-proof on-chain records for every approved work session, creating a portable and verifiable proof of delivery.

Every time a payment is released on Aven, the Stream Contract calls the Attestation Contract to mint a permanent, immutable record on the Stellar ledger. These records — called attestations — prove that a specific worker completed a specific amount of verified work on a specific stream. Because they live on-chain, they cannot be edited or deleted by any party, including Aven.

## Purpose

Attestations serve two purposes:

1. **Proof of delivery** — each attestation captures the evidence hash of the verifier's work report, the active seconds recorded by the CLI, the exact amount paid, and whether the employer explicitly confirmed the work.
2. **Reputation input** — `StreamCompletion` attestations (one per fully-paid stream) are read by the Reputation Contract to compute a worker's portable score.

> [!NOTE]
>
> Two attestation records are minted per payment release when the stream is fully paid out: one `WorkSession` record for the individual session and one `StreamCompletion` record used for reputation scoring.

***

## AttestationRecord

Every minted attestation is stored as an `AttestationRecord` with the following fields:

| Field | Type | Description |
| - | - | - |
| `id` | `u64` | Auto-incrementing attestation identifier |
| `kind` | `AttestationKind` | `WorkSession`, `LegacyReviewed`, `StreamCompletion`, or `Checkpoint` |
| `stream_id` | `u64` | The stream this attestation belongs to |
| `request_id` | `String` | Work-session identifier from the verifier (empty for `Checkpoint` kind) |
| `checkpoint_index` | `u32` | Legacy field; always `0` for work-session and completion records |
| `sender` | `Address` | Employer's Stellar address |
| `recipient` | `Address` | Worker's Stellar address |
| `amount_paid` | `i128` | Amount paid in Stellar 7-decimal fixed-point |
| `asset` | `Address` | Stellar asset contract address |
| `category` | `Category` | Work category inherited from the parent stream |
| `title` | `String` | Stream title inherited from the parent stream |
| `period_start_ledger` | `u32` | Ledger when the tracked work period began |
| `period_end_ledger` | `u32` | Ledger when the payment was released |
| `active_duration_seconds` | `u64` | Verified active seconds from the CLI (0 for `StreamCompletion`) |
| `minted_at_ledger` | `u32` | Ledger when the attestation was minted |
| `client_confirmed` | `bool` | `true` if the employer explicitly approved; `false` on auto-release |
| `auto_released` | `bool` | `true` if the payment was released automatically after the deadline |
| `verifier` | `Option<Address>` | Verifier service address that signed the work report (None for legacy paths) |
| `report_hash` | `Option<BytesN<32>>` | SHA-256 of the verifier's work-session report (None for legacy paths) |

### AttestationKind

| Variant | Description |
| - | - |
| `WorkSession` | Standard verified work session via the `aven-stellar` CLI and verifier service |
| `LegacyReviewed` | Direct `request_withdrawal` path used before the verifier was deployed |
| `StreamCompletion` | One record minted when a stream is fully paid out; used for reputation scoring |
| `Checkpoint` | Legacy finalized checkpoint payment (retained for historical compatibility) |

***

## Public Entrypoints

### `mint_attestation`

Mints a new `AttestationRecord` and indexes it by recipient and sender.

```rust theme={null}
mint_attestation(
    caller, kind, stream_id, request_id, checkpoint_index,
    sender, recipient, amount_paid, asset, category, title,
    period_start_ledger, period_end_ledger, active_duration_seconds,
    client_confirmed, auto_released, verifier, report_hash
) → u64  // returns the new attestation_id
```

> [!WARNING]
>
> You do not call `mint_attestation` directly. The contract enforces that only the registered Stream Contract address can call it — any other caller receives **Error 3: Unauthorized**. Aven calls it automatically when `withdraw_approved` succeeds.

The contract validates:

* Only the registered Stream Contract (`caller` must match) can mint.
* `amount_paid` must be greater than 0.
* `period_start_ledger` must not exceed `period_end_ledger`.
* Title must not exceed 80 bytes.
* `WorkSession` records must include a non-empty `request_id`, non-zero `active_duration_seconds`, a `verifier` address, and a `report_hash`.
* Duplicate prevention: a second `WorkSession` or `LegacyReviewed` record with the same `(stream_id, request_id)` pair is rejected with **Error 10: DuplicateAttestation**. Similarly, only one `StreamCompletion` record per stream is permitted.

***

### `get_attestation`

Returns the full `AttestationRecord` for a given attestation ID.

```rust theme={null}
get_attestation(attestation_id: u64) → AttestationRecord
```

Returns **Error 4: AttestationNotFound** if the ID does not exist.

***

### `get_recipient_attestations`

Returns a list of attestation IDs for a given recipient address.

```rust theme={null}
get_recipient_attestations(recipient: Address) → Vec<u64>
```

Returns an empty list if the address has no attestations. The list is ordered by creation and is capped at 1,000 entries per address. Use the returned IDs with `get_attestation` to fetch individual records.

***

### `get_sender_attestations`

Returns a list of attestation IDs for a given sender address.

```rust theme={null}
get_sender_attestations(sender: Address) → Vec<u64>
```

Useful for employers who want to verify payments they approved on-chain.

***

### `verify_attestation`

Returns `true` if an attestation exists and has a positive `amount_paid`.

```rust theme={null}
verify_attestation(attestation_id: u64) → bool
```

This is a lightweight existence check. For full verification — including confirming the stream, verifier, and report hash — use `get_attestation` and inspect the fields directly, or use the `/verify` page in the Aven dashboard.

***

## How Attestations Are Minted

**1. Payment is released**

The recipient calls `withdraw_approved` on the Stream Contract. The contract transfers funds to the recipient.

**2. Stream Contract calls the Attestation Contract**

The Stream Contract immediately invokes `mint_attestation` as a cross-contract call. The caller is the Stream Contract's own address — this is what passes the authorization check.

**3. WorkSession record is minted**

An attestation of kind `WorkSession` is minted with the session evidence hash, active duration, verifier address, and payment amount.

**4. StreamCompletion record (if applicable)**

If `total_withdrawn == total_deposited`, the stream is now fully paid out. The Stream Contract immediately mints a second attestation of kind `StreamCompletion`. This is the record read by the Reputation Contract.

***

## Querying Your Attestations

> [!NOTE]
>
> You do not call `mint_attestation` directly. Aven calls it automatically when a payment is released. You can view your attestations on your dashboard profile page, or query them on-chain by calling `get_recipient_attestations` with your Stellar address.

**From the dashboard:** Navigate to `/profile/[your-address]` to see all your attestations, their amounts, durations, employer confirmations, and stream titles.

**Independently:** You can call `get_recipient_attestations` directly against the Attestation Contract using the `stellar-sdk` or Stellar Laboratory. The returned list of IDs can then be fetched one-by-one with `get_attestation`.

***

## Independent Verification

To verify any attestation without using the Aven frontend:

**1. Visit the verify page**

Navigate to `/verify` in the Aven dashboard and enter the attestation ID.

**2. Or call verify\_attestation on-chain**

Call `verify_attestation(attestation_id)` on the Attestation Contract. A return value of `true` confirms the record exists with a positive `amount_paid`.

**3. Inspect the full record**

Call `get_attestation(attestation_id)` to retrieve all fields, including `report_hash`, `verifier`, `client_confirmed`, and `auto_released`. Cross-reference `report_hash` with the work report stored in the Aven verifier service for full end-to-end verification.

> [!TIP]
>
> Third-party systems — such as hiring platforms or automated grant workflows — can call `get_recipient_attestations` and `get_attestation` directly from any Stellar SDK without any Aven-specific dependency.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.