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

# How Aven Works: From Stream to On-Chain Reputation

> A full walkthrough of the Aven lifecycle: payment streaming, privacy-first work tracking, atomic on-chain verification, and reputation aggregation.

When a client creates an Aven stream, funds are locked in a smart contract on Stellar and begin flowing to the worker at a pre-set rate per second. The worker runs a lightweight CLI that monitors activity in their local Git repository — never touching file contents — and submits a signed report when the session ends. A verifier checks the report, then triggers a single atomic transaction on Stellar that simultaneously releases the earned payment and mints a permanent attestation record. That attestation feeds the reputation contract, which updates the worker's on-chain score. Every step is transparent, cryptographically proven, and owned by the participants — not by Aven.

## Full Lifecycle at a Glance

```mermaid theme={null}
flowchart TD
    A[1. Client creates Stream] -->|USDC / XLM locked in contract| B[2. Worker runs local CLI]
    B -->|Tracks Git activity & timing| C[3. Session submitted to Dashboard]
    C -->|Verified by verifier key| D[4. Atomic Verification on Stellar]
    D -->|SUCCESS| E[5. Worker gets Paid & Attestation is Minted]
    D -->|FAIL| F[Transaction Reverted]
    E -->|Reputation Contract| G[6. Reputation Score Bumps]
```

## Step-by-Step Breakdown

<Steps>
  <Step title="Payment Streaming">
    A client opens the Aven Dashboard, connects their Freighter wallet (configured for Testnet), and creates a payment stream. They specify the recipient worker address, the token (USDC or XLM), the total amount, and the rate per second. The full amount is locked inside the `stream_contract` on Stellar — the client cannot spend it on anything else while the stream is active.

    Clients retain full control throughout: a stream can be **paused**, **resumed**, or **cancelled** at any time. If cancelled, any unearned funds are returned. Only verified, attested work unlocks a payout.
  </Step>

  <Step title="Work Tracking">
    The worker opens a terminal inside the Git repository where the work will happen and starts a session:

    ```bash theme={null}
    npx aven-stellar start --stream <your-stream-id>
    ```

    On first use, the CLI asks for the Dashboard URL and opens a browser tab for one-time wallet authorization. After that, it launches a background activity watcher that records:

    * Active working time (seconds)
    * The current Git branch
    * Commit metadata and timestamps
    * Relative file paths of changed files
    * Addition and deletion line counts (diff sizes)

    The worker then works normally, makes commits as usual, and lets Aven do the tracking in the background. The CLI also creates an `.avenignore` file and respects your existing `.gitignore`, so sensitive paths are never touched.
  </Step>

  <Step title="Submission & Verification">
    When the work period ends, the worker stops the session:

    ```bash theme={null}
    npx aven-stellar stop --message "Implemented the assigned validation changes"
    ```

    The CLI calculates the earned payment amount from tracked active seconds multiplied by the stream's on-chain rate (capped at currently available funds), generates a structured JSON report, previews it for the worker to review, and — with confirmation — uploads it to the Aven Dashboard.

    The Dashboard's automated verifier then validates the session's Git statistics against the requested payment amount and countersigns the report with its verifier key. The stream sender can also manually review the session before approval.

    <Tip>
      AI agents and automated workers can skip confirmation prompts with `--non-interactive` on `start` and `--submit` on `stop`, making the entire flow hands-free.
    </Tip>
  </Step>

  <Step title="Atomic Execution on Stellar">
    Once a session is verified and the worker (or agent) triggers the claim, the protocol executes a single Stellar transaction that calls two contracts at once:

    1. **`stream_contract`** — transfers the earned token amount from the locked stream to the worker's wallet.
    2. **`attestation_contract`** — mints a permanent `AttestationRecord` on-chain, linking the worker's address, the session details, and the payment amount.

    These two operations are **indivisible**. See the [Atomicity Guarantee](#atomicity-guarantee) section below for the full guarantee.
  </Step>

  <Step title="Reputation Aggregation">
    After the attestation is minted, the `reputation_contract` automatically scans all attestations associated with the worker's Stellar address and recomputes a categorized reputation score. Scores are broken down by work type:

    | Category         | Description                                  |
    | ---------------- | -------------------------------------------- |
    | **Freelance**    | Project-based or hourly contract work        |
    | **Salary**       | Ongoing employment-style streams             |
    | **Bounty**       | Task-specific, completion-triggered payments |
    | **Grant**        | Milestone-based funding streams              |
    | **AgentTask**    | Autonomous AI agent contributions            |
    | **Subscription** | Recurring service or retainer streams        |

    The score reflects actual on-chain payment volumes, not self-reported claims.
  </Step>

  <Step title="Portable Proof">
    Every attestation is an on-chain record owned by the worker's wallet address — not stored on Aven's servers and not controlled by the client. Workers accumulate a permanent, verifiable work history that they can present to any platform, DAO, or employer that reads Stellar ledger data.

    AI agents benefit from the same portability: a machine reputation score built through Aven is a first-class, cryptographically verifiable identity that autonomous agents can carry across projects and platforms.
  </Step>
</Steps>

## Protocol Component Map

```mermaid theme={null}
mindmap
  root((Aven Protocol))
    Clients
      Create Streams
      Fund with USDC or XLM
      Pause / Resume / Cancel
      Review & Approve Sessions
    Workers
      Run aven-stellar CLI
      Track Git Activity
      Submit Work Reports
      Build Reputation
    AI Agents
      Non-interactive Mode
      Automated Submissions
      Machine Reputation
    Smart Contracts
      Stream Contract
      Attestation Contract
      Reputation Contract
    Dashboard
      Stream Management
      Session Review
      Wallet Connection
```

## Atomicity Guarantee

<Warning>
  Payment and attestation are a **single, atomic Stellar transaction** — they cannot be separated. If the token transfer to the worker fails for any reason, no attestation is minted. If the attestation mint fails for any reason, the entire transaction reverts and the worker receives no funds. There is no state in which a worker is paid without an on-chain record, and no state in which an attestation exists without the corresponding payment having succeeded.

  This guarantee is enforced at the smart-contract level and cannot be overridden by the Dashboard, the verifier, or any off-chain process.
</Warning>

## Privacy Guarantee

The Aven CLI is designed to give verifiable proof of contribution without exposing your intellectual property. Here is exactly what the CLI collects and what it never touches:

**What the CLI collects:**

* Session start and stop timestamps (active working time in seconds)
* The name of the active Git branch
* Commit hashes, commit messages, and commit timestamps
* Relative file paths of changed files (e.g. `src/utils/parser.ts`)
* Line-level addition and deletion counts (diff sizes, not diff content)

**What the CLI never collects:**

* File contents or source code of any kind
* Keystrokes, clipboard contents, or screenshots
* Your Stellar secret key or wallet seed phrase
* Files excluded by `.gitignore` or `.avenignore`
* Output from running your project's code or tests
* Any data from outside the tracked Git repository

<Note>
  Local session state is stored in a `.aven/` directory inside your repository. This directory is automatically added to `.avenignore` and should not be committed to version control. It contains only the recoverable state needed to resume or stop an active session — never your wallet credentials.
</Note>