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

# Aven Smart Contracts: Stellar-Native Protocol Layer

> Three Soroban smart contracts on Stellar forming Aven's atomic payment-verification-reputation system — stream, attest, and score in one protocol.

Aven's protocol is implemented as three Soroban smart contracts on Stellar, collectively forming an atomic payment-verification-reputation system. Each contract owns a distinct responsibility — escrow and lifecycle management, permanent proof-of-work records, and on-chain score computation — and the three are wired together so that a single Stellar transaction can pay a worker, mint their attestation, and update the inputs to their reputation score simultaneously.

## The Three Contracts

<CardGroup cols={3}>
  <Card title="Stream Contract" icon="circle-dollar-to-slot" href="/contracts/stream-contract">
    Manages payment streams — creation, fund escrow, verification, payout, pause, resume, and cancel. The entry point for every economic interaction in Aven.
  </Card>

  <Card title="Attestation Contract" icon="certificate" href="/contracts/attestation-contract">
    Mints permanent on-chain records whenever a verified work session is paid. Every attestation is stored on the Stellar ledger and is publicly readable.
  </Card>

  <Card title="Reputation Contract" icon="star" href="/contracts/reputation-contract">
    Reads all attestations for a given address and computes a weighted, category-based reputation score that workers own and can present anywhere.
  </Card>
</CardGroup>

## System Architecture

The diagram below shows how a single verified payout flows through all three contracts and produces a reputation score.

```mermaid theme={null}
flowchart TD
    Client[Client] -->|create_stream| SC[Stream Contract]
    Worker[Worker] -->|via Dashboard| SC
    SC -->|withdraw_approved / approve_checkpoint| AC[Attestation Contract]
    SC -->|transfer tokens| Worker
    AC -->|mint_attestation| Ledger[(Stellar Ledger)]
    Ledger -->|get_recipient_attestations| RC[Reputation Contract]
    RC -->|compute_score| Score[Reputation Score]

    style SC fill:#7C3AED,color:#fff
    style AC fill:#7C3AED,color:#fff
    style RC fill:#7C3AED,color:#fff
```

## Deployed Contract Addresses (Testnet)

All three contracts are currently live on **Stellar Testnet**.

| Contract             | Address                                                    |
| -------------------- | ---------------------------------------------------------- |
| Stream Contract      | `CAZSE5UHSWNF62K26OZKOL7BSFB2647CXRPOICHUDCUJ5EKS4NCOA6ZA` |
| Attestation Contract | `CD22NZLAI53Y2LZB2GNLVITQXZWGZ3AQ6QKVKNUDKWABIIQIDEFSPQCG` |
| Reputation Contract  | `CANK4E7GOFZT4D3U57RNT7QLQTNFGY7QNL6TQTWWKYBNHX7J6U54HO7E` |

## Atomicity Guarantee

<Warning>
  The stream contract calls the attestation contract in the **same Stellar transaction** as the token transfer. Both succeed or both revert — there is no partial state. This guarantees workers are only paid when attestations are created, and attestations are only created when workers are paid. You cannot mint a reputation record without real economic activity behind it.
</Warning>

## TypeScript Bindings

Aven provides auto-generated TypeScript bindings for all three contracts in the `contracts/bindings/` directory, making it straightforward to interact with the contracts from any JavaScript or TypeScript application. The bindings export a typed `Client` class per contract with full inline documentation for every method.

```json theme={null}
"dependencies": {
  "stream":      "./contracts/bindings/stream",
  "attestation": "./contracts/bindings/attestation",
  "reputation":  "./contracts/bindings/reputation"
}
```