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

# How Aven Works: From Stream Creation to Payment Release

> Walk through Aven's end-to-end flow: creating a funded stream, tracking work sessions with the CLI, submitting reports, and releasing verified payments.

Aven ties every payment to a cryptographically verified record of active work. An employer creates a stream — specifying the recipient, asset, rate per second, total budget, and duration — and deposits funds into a Soroban smart contract. The freelancer installs the `aven-stellar` CLI, authorizes it once with their Freighter wallet, and then runs `aven-stellar start` inside their Git repository when work begins. The CLI quietly tracks active coding time and Git change statistics in the background. When the freelancer stops the session, the CLI generates a structured work report and submits it to the dashboard. The payment amount — calculated as `active seconds × stream rate` — is reserved in escrow automatically. The employer reviews the report in the dashboard and approves it — the contract releases the reserved payment to the freelancer's wallet and mints an immutable attestation as portable proof of delivery.

## End-to-end flow

```mermaid theme={null}
flowchart LR
  A["Employer funds stream"] --> B["Freelancer authorizes CLI"]
  B --> C["aven-stellar start"]
  C --> D["Active work tracked"]
  D --> E["aven-stellar stop"]
  E --> F["Report submitted"]
  F --> G["Employer reviews"]
  G --> H["Contract releases payment"]
  H --> I["Attestation minted"]
```

## Step-by-step lifecycle

**1. Employer creates a funded stream**

The employer navigates to `/stream/create` in the Aven dashboard and completes a guided four-step form. They set the **recipient** (the freelancer's Stellar wallet address), the **asset** (XLM or testnet USDC), the **rate per second**, the **total budget**, the **duration** (expressed in Stellar ledgers), a **category**, and a **title**. After confirming the details, they approve a Freighter transaction that deposits the total budget into the Soroban smart contract escrow. The funds are held by the contract — neither Aven nor the employer can unilaterally redirect them once the stream is active.

**2. Freelancer installs the CLI and authorizes with Freighter**

The freelancer opens a terminal inside the Git repository where they will work and runs:

```bash theme={null}
npx aven-stellar start
```

On first use, the CLI prompts for the Aven dashboard URL and the stream ID shared by the employer. It then opens the dashboard's `/cli/authorize` page, where the freelancer signs a short-lived device authorization request with Freighter. The resulting token is scoped to that worker's streams — it can submit sessions and request review, but it cannot create streams or approve the worker's own requests. The CLI stores the token and stream configuration in `.aven/config.json` inside the repository. **The CLI never receives or stores the wallet secret key.**

**3. CLI tracks active coding time and Git changes**

Once authorized, `aven-stellar start` launches a lightweight background activity watcher as a detached process. The watcher monitors the repository for file-system events and periodically records active time, distinguishing genuine coding activity from idle periods. It captures Git state at session start — the current branch, the HEAD commit, and whether the working tree is dirty — and continues sampling throughout the session. The worker codes normally and commits changes as usual.

**4. Freelancer stops the session and submits a work report**

When the work period is finished, the freelancer runs:

```bash theme={null}
npx aven-stellar stop
```

The CLI stops the watcher, calculates the final Git change statistics (branch, commits, relative changed paths, additions, deletions), and assembles a complete work-session report. The report is displayed for review before submission. The freelancer can include a written delivery summary with `--message`, or pass `--submit` to skip the second confirmation prompt. For a **final project delivery**, the `--ended` flag additionally prompts for delivery branches, verifies their remote head commits against the connected GitHub repository, and requests settlement of the remaining unreserved escrow.

If submission fails after the session is stopped, running `aven stop` again retries with the original stop time — the delay is not counted as additional work.

**5. Contract verifier reserves the payment amount**

When the report reaches the dashboard, the configured verifier reads the active seconds from the session and calculates:

```
verified active seconds × stream rate per second
```

This amount is **capped by the stream's remaining unreserved escrow** and checked independently by the Soroban smart contract. The contract reserves that exact amount automatically. Workers never enter their own payment figure — the reservation is computed entirely from on-chain stream parameters and the verified time record.

**6. Employer approves → contract releases payment → attestation minted**

The employer sees the submitted session under **WORK SESSIONS** on the stream page. They can review the full report — timing, Git statistics, delivery branches, and the worker's statement — and then **approve** or **dispute** it. An approved session triggers the escrow contract to release the reserved payment directly to the freelancer's Stellar wallet. Simultaneously, the attestation contract mints a permanent on-chain record of the session. This attestation is publicly visible on the worker's `/profile/[address]` page and independently verifiable at `/verify`, forming a portable, address-linked work history.

## Who does what

| Employer actions | Freelancer actions |
| - | - |
| Create and fund a payment stream | Install `aven-stellar` and authorize the CLI with Freighter |
| Share the stream ID with the freelancer | Run `aven-stellar start` inside the project repository |
| Monitor active streams in the dashboard | Work normally and commit changes to Git |
| Review submitted work-session reports | Run `aven-stellar stop` to generate and submit a report |
| Approve or dispute a session | Optionally add a written delivery summary with `--message` |
| Release payment by approving the session | Request final settlement with `aven-stellar stop --ended` |
| View the worker's public attestation profile | Track earnings and attestations in the dashboard |

## Payment formula

The amount released for any single approved session is:

```
payment = verified active seconds × stream rate per second
```

This calculation has three important properties:

* **Capped by unreserved escrow.** If the calculated amount exceeds the escrow balance that has not already been reserved for pending sessions, the contract caps the reservation at the available balance. Workers can never be paid more than the funded budget.
* **Enforced on-chain.** The Soroban escrow contract independently verifies the reservation amount. No off-chain component — including the Aven dashboard itself — can override the contract's arithmetic.
* **Never worker-entered.** The payment amount is derived entirely from the rate per second set by the employer at stream creation and the active seconds reported by the CLI. Workers have no input field for their own payment amount.

For final sessions submitted with `--ended`, the contract caps the verified payment to the exact remaining escrow balance. The real active seconds tracked by the CLI are preserved in the human-readable report you review before approving.

## What is verified

> [!WARNING]
>
> Aven is a **privacy-conscious** system. The CLI is deliberately designed to collect the minimum metadata needed to verify delivery — nothing more.

The work-session report **always includes**:

* Session start time, stop time, and total active seconds (idle time excluded)
* Active Git branch name at session start and stop
* HEAD commit hash and commit message
* Relative paths of changed files (not their contents)
* Per-file additions and deletions (diff statistics)
* Git status of the working tree
* The worker's optional written delivery statement

The CLI **never records or uploads**:

* Complete source file contents
* Keystrokes, mouse activity, or screenshots
* The worker's Stellar secret key or any wallet credential
* Project test output or build artifacts
* Files excluded by `.gitignore` or `.avenignore`
* Any paths outside the tracked Git repository

Local, recoverable session state is stored in `.aven/` inside the repository. **Do not commit this directory.**


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