> ## 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.

# Aven Smart Contract Architecture on Stellar Soroban

> Aven runs on three Soroban smart contracts on Stellar: the Stream Contract, Attestation Contract, and Reputation Contract — each with a distinct role.

Aven's trust guarantees come from Soroban smart contracts running on Stellar. All payment logic, escrow management, attestation minting, and reputation scoring happen entirely on-chain. No server can move funds, forge work records, or alter scores — every action is enforced by the contracts and visible on the ledger.

## Architecture

The diagram below shows how the Aven frontend, CLI, and verifier service interact with each contract and how the contracts call one another.

```mermaid theme={null}
graph TD
  User["Employer / Freelancer"] --> Dashboard["Aven Dashboard"]
  Dashboard --> SC["Stream Contract\n(Escrow & Payments)"]
  Dashboard --> AC["Attestation Contract\n(Work Proofs)"]
  Dashboard --> RC["Reputation Contract\n(Scoring)"]
  SC -->|mint attestation on release| AC
  AC -->|attestations feed| RC
  CLI["aven-stellar CLI"] --> Dashboard
  Verifier["Verifier Service"] --> SC
```

## Contract Roles

| Contract | Purpose | Key Interactions |
| - | - | - |
| **Stream Contract** | Creates payment streams, holds escrow, enforces payment math, manages the approval workflow | Employers create streams; the verifier calls `verify_work`; employers approve or dispute; recipients call `withdraw_approved` to release funds |
| **Attestation Contract** | Mints permanent, tamper-proof on-chain work proofs on every approved payment | Called automatically by the Stream Contract when a payment is released — not invoked directly by users |
| **Reputation Contract** | Reads `StreamCompletion` attestations and aggregates them into a portable score | Read-only for public consumers; queries the Attestation Contract by cross-contract call |

## How the Contracts Relate

**1. Stream is created**

An employer calls `create_stream` on the Stream Contract. Funds are transferred into the contract as escrow immediately.

**2. Work is tracked and verified**

The worker runs `aven-stellar` locally. When the session ends, the Aven verifier service calls `verify_work` on the Stream Contract, which independently recomputes the payment amount and creates a `WithdrawalRecord` in `Pending` status.

**3. Employer reviews**

The employer calls `approve_withdrawal` or `dispute_withdrawal`. If the approval deadline passes without action, the worker can still claim the payment automatically (auto-release).

**4. Payment is released and attested**

The worker calls `withdraw_approved`. Funds are transferred to the recipient and the Stream Contract immediately calls `mint_attestation` on the Attestation Contract. If the stream is now fully paid out, a `StreamCompletion` attestation is also minted.

**5. Reputation is updated**

The Reputation Contract reads `StreamCompletion` attestations on demand when `compute_score` or `get_score_breakdown` is called. No extra transaction is required — scores update automatically as attestations accumulate.

## Contract IDs

Each deployed Aven instance exposes three public environment variables that identify the contracts on Stellar testnet:

| Variable | Contract |
| - | - |
| `NEXT_PUBLIC_STREAM_CONTRACT_ID` | Stream Contract |
| `NEXT_PUBLIC_ATTESTATION_CONTRACT_ID` | Attestation Contract |
| `NEXT_PUBLIC_REPUTATION_CONTRACT_ID` | Reputation Contract |

> [!NOTE]
>
> These values are set by the Aven deployment and are already configured in the live application. You do not need to set or know them to use the dashboard. They are public (`NEXT_PUBLIC_`) because the browser Stellar SDK uses them directly to build transactions — no secrets are exposed.

## Contract Pages

> **[Stream Contract](https://aven-docs.mintlify.site/contracts/stream-contract.md)**
>
> Escrow, work verification, approval workflow, and payment release.

> **[Attestation Contract](https://aven-docs.mintlify.site/contracts/attestation-contract.md)**
>
> Permanent on-chain work proofs minted on every approved payment.

> **[Reputation Contract](https://aven-docs.mintlify.site/contracts/reputation-contract.md)**
>
> Scoring based on your verified on-chain work history.


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