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 — installed in your browser and configured for Testnet
• A funded Testnet account — use the Stellar Laboratory Friendbot to fund a new address instantly
• A Git repository (workers only) — the CLI monitors activity inside an existing Git repo

---

I'm a Client

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

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

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

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

I'm a Worker

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

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

3. Install the CLI

   You can run the Aven CLI directly with npx (no installation required) or install it globally for a shorter command:

   npm

   npx aven-stellar start
   

   global install

   npm install --global aven-stellar
   aven start
   
4. Start a Work Session

   Open a terminal inside the Git repository where your work will happen, then run:

   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.

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

6. Stop and Submit

   When you are ready to end the session, run:

   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:

   npx aven-stellar stop --message "Implemented input validation and added unit tests" --ended --submit
   
7. 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.

---

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.

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.

Next Steps

Understand Streams

Learn how payment streams work on-chain, including rate calculation, pausing, and dispute resolution.

CLI Reference

Explore every command and flag available in the aven-stellar CLI.

Privacy Guarantees

See exactly what the CLI collects, what it never touches, and how .avenignore works.

Reputation System

Understand how on-chain attestations roll up into a portable, category-based reputation score.