> ## 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 Quickstart: Your First Stream and Work Session

> Set up your first Aven payment stream or work session on Stellar Testnet. Covers both client and worker roles from wallet connection to first payout.

Aven has two primary roles — **Client** (funds and manages streams) and **Worker** (tracks work and claims payment). Clients lock USDC or XLM into a payment stream on Stellar; workers run a lightweight CLI to record verifiable activity against that stream, then submit a session report for review. This quickstart walks both roles through their first complete session on Stellar Testnet.

## Prerequisites

Before you begin, make sure you have the following ready:

* **Node.js v20 or newer** — required to run the Aven CLI
* **[Stellar Freighter Wallet](https://www.freighter.app/)** — installed in your browser and configured for Testnet
* **A funded Testnet account** — use the [Stellar Laboratory Friendbot](https://laboratory.stellar.org/#account-creator?network=test) to fund a new address instantly
* **A Git repository** *(workers only)* — the CLI monitors activity inside an existing Git repo

***

<Tabs>
  <Tab title="I'm a Client">
    <Steps>
      <Step title="Connect Your Wallet">
        Open the Aven dashboard and click **Connect Wallet** in the top navigation bar. A Freighter pop-up will appear asking you to authorize the connection. Confirm the authorization — Aven never receives your private key.

        Once connected, your Testnet address and XLM balance appear in the header.
      </Step>

      <Step title="Create a Stream">
        Navigate to **Streams → Create** in the dashboard sidebar. Fill in the stream details:

        | Field                 | Description                             |
        | --------------------- | --------------------------------------- |
        | **Recipient address** | The worker's Stellar Testnet public key |
        | **Total amount**      | Maximum funds to lock in the contract   |
        | **Duration**          | Total length of the engagement          |
        | **Currency**          | `USDC` or `XLM`                         |

        When you click **Create Stream**, Freighter will ask you to sign the on-chain transaction. Approve it to lock the funds in the stream contract.
      </Step>

      <Step title="Monitor Progress">
        Your newly created stream appears on the **Streams** dashboard page, showing its live status, elapsed time, and remaining balance. You can take any of these actions at any time:

        * **Pause** — temporarily halts payment accrual
        * **Resume** — restarts the stream from its current balance
        * **Cancel** — closes the stream and returns unspent funds

        Incoming session submissions from your worker appear under the **WORK SESSIONS** tab on the stream's detail page.
      </Step>

      <Step title="Review and Approve">
        When a worker submits a session, you will see it listed under **WORK SESSIONS** with a status of *Pending Review*. Open the session to examine the Git statistics, active time, and the worker's written summary.

        * Click **Approve** to release payment and mint an on-chain attestation atomically.
        * Click **Dispute** if the submission requires further discussion before funds are released.

        Payment and attestation are executed in a single Stellar transaction — if either step fails, the entire transaction reverts.
      </Step>
    </Steps>
  </Tab>

  <Tab title="I'm a Worker">
    <Steps>
      <Step title="Connect Your Wallet">
        Open the Aven dashboard and click **Connect Wallet** in the top navigation bar. Authorize Freighter when prompted. Aven uses your wallet for signing session submissions — it never requests your secret key.
      </Step>

      <Step title="Find Your Stream">
        Ask your client to share the **stream ID** for your engagement. Open the stream's detail page on the dashboard and confirm that your wallet address is listed as the **recipient**. If your address does not match, do not proceed — contact the client to create a new stream with the correct address.
      </Step>

      <Step title="Install the CLI">
        You can run the Aven CLI directly with `npx` (no installation required) or install it globally for a shorter command:

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

        ```bash global install theme={null}
        npm install --global aven-stellar
        aven start
        ```
      </Step>

      <Step title="Start a Work Session">
        Open a terminal inside the Git repository where your work will happen, then run:

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

        On first use, the CLI will ask for the dashboard URL and then open it in your browser so you can authorize your wallet. After you authorize, the CLI launches a lightweight background watcher — you are free to switch back to your editor. The CLI never receives your wallet secret key.
      </Step>

      <Step title="Work Normally">
        Write code, make commits, and work as you usually would. The CLI monitors your Git activity (branches, commit metadata, changed file paths, and diff sizes) and tracks your active time in the background. It does not read file contents, record keystrokes, or upload your source code.
      </Step>

      <Step title="Stop and Submit">
        When you are ready to end the session, run:

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

        The CLI calculates the Git change statistics, displays a full session report for your review, and asks for confirmation before submitting. Once you confirm, the report is uploaded to the dashboard and appears under **WORK SESSIONS** on your stream's detail page.

        You can customise the submission with optional flags:

        | Flag                 | What it does                                                                    |
        | -------------------- | ------------------------------------------------------------------------------- |
        | `--message "<text>"` | Attaches a written summary to your session report                               |
        | `--submit`           | Skips the confirmation prompt and submits immediately after the preview         |
        | `--ended`            | Marks the engagement as complete and requests the full remaining stream balance |

        Example using all three:

        ```bash theme={null}
        npx aven-stellar stop --message "Implemented input validation and added unit tests" --ended --submit
        ```
      </Step>

      <Step title="Await Approval">
        The stream sender receives a notification and reviews your session. Once they approve, the stream contract transfers the earned funds to your wallet and the attestation contract mints a permanent `AttestationRecord` on the Stellar ledger — both in the same atomic transaction. Your reputation score is updated automatically.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

<Note>
  This quickstart uses **Stellar Testnet** throughout. Testnet transactions are not real and have no monetary value. Never use a mainnet-funded wallet during testing — keep a dedicated Testnet account seeded with Friendbot funds.
</Note>

<Tip>
  Workers can create a `.avenignore` file in the root of their repository to exclude sensitive paths from the session report. The CLI also respects `.gitignore` automatically. Any path listed in either file will never appear in the submitted report.
</Tip>

## Next Steps

<CardGroup cols={2}>
  <Card title="Understand Streams" icon="water" href="/concepts/payment-streams">
    Learn how payment streams work on-chain, including rate calculation, pausing, and dispute resolution.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/commands">
    Explore every command and flag available in the `aven-stellar` CLI.
  </Card>

  <Card title="Privacy Guarantees" icon="shield-check" href="/cli/privacy">
    See exactly what the CLI collects, what it never touches, and how `.avenignore` works.
  </Card>

  <Card title="Reputation System" icon="star" href="/concepts/reputation">
    Understand how on-chain attestations roll up into a portable, category-based reputation score.
  </Card>
</CardGroup>