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
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: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: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: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
Payment formula
The amount released for any single approved session is:- 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.
--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
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
- 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
.gitignoreor.avenignore - Any paths outside the tracked Git repository
.aven/ inside the repository. Do not commit this directory.