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

# Work Sessions: Privacy-First Contribution Proof on Aven

> A work session is a privacy-first record of Git activity tied to a stream — proving what changed during a work period without exposing your source code.

A work session is a recorded period of activity tied to a specific payment stream. When you run the `aven-stellar` CLI inside your Git repository, it tracks how long you were actively working and what changed in the codebase — then packages that evidence into a structured report that you can review before submitting to your client for approval.

## What a Session Captures

Every work session report contains the following categories of data:

* **Session timing** — the wall-clock start and end times, total elapsed seconds, active seconds (time with detected activity), and idle seconds. Payment is calculated from active seconds only.
* **Git repository state** — the branch name at session start and end, the starting commit hash, and the ending commit hash. This anchors the session to an exact snapshot of the repository.
* **File change summary** — relative file paths, change type (`created`, `modified`, `deleted`, or `renamed`), line additions and deletions, and the file category (`source`, `test`, `documentation`, `configuration`, etc.). Files excluded by `.gitignore` or `.avenignore` are never included.
* **Commit history** — each commit made during the session, including its hash, message, timestamp, and diff size (additions/deletions). Full file contents are never uploaded.
* **Worker statement** — an optional plain-text summary you can provide with `--message` when stopping the session. This gives you space to explain decisions, blockers, or context that the Git data alone does not convey.
* **Payment request** — the amount you are requesting, calculated automatically as `active_seconds × stream_rate_per_second`, capped by the funds currently available in the stream.

## Session Report Structure

The complete shape of a submitted report is defined by the `WorkSessionReport` type in the CLI package:

```typescript theme={null}
export type WorkSessionReport = {
  schemaVersion: 1;
  session: {
    sessionId: string;
    projectId: string;
    streamId: string;
    workerAddress: string;
    startedAt: string;
    endedAt: string;
    totalSeconds: number;
    activeSeconds: number;
    idleSeconds: number;
    packageVersion: string;
    ended?: boolean;
  };
  repository: {
    repositoryId: string;
    branchAtStart: string;
    branchAtEnd: string;
    startingCommit?: string;
    endingCommit?: string;
    dirtyAtStart: boolean;
    dirtyAtEnd: boolean;
  };
  changes: {
    changedFiles: FileChangeSummary[];
    additions: number;
    deletions: number;
    commits: CommitSummary[];
    testsChanged: number;
    documentationFilesChanged: number;
    generatedFilesExcluded: number;
  };
  workerStatement?: { message: string; providedAt: string };
  localVerification: {
    verifierVersion: string;
    workType: "code" | "writing" | "image" | "mixed";
    flags: string[];
    summary: string;
  };
  paymentRequest: {
    requestedAmount: string;
    asset: "USDC" | "XLM";
    calculation?: "active_time_x_stream_rate" | "flat_rate";
    ratePerSecond?: string;
    billableSeconds?: number;
  };
  privacy: {
    profile: "standard";
    excludedFileCount: number;
    secretWarnings: number;
    fullFilesIncluded: false;
  };
};
```

## Session Lifecycle

```mermaid theme={null}
flowchart LR
    A[Worker starts session] --> B[CLI monitors activity]
    B --> C[Worker stops session]
    C --> D[Report generated]
    D --> E[Worker reviews & submits]
    E --> F[Dashboard receives report]
    F --> G{Client reviews}
    G -->|Approve| H[Atomic payout + attestation]
    G -->|Dispute| I[Dispute resolution]
```

The session does not submit anything automatically. You always see the full report and confirm before it is sent to the dashboard.

## Work Session States

| State       | Description                                                                  |
| ----------- | ---------------------------------------------------------------------------- |
| `Pending`   | The session has been submitted and is awaiting client review                 |
| `Approved`  | The client has verified the session; payout and attestation are in progress  |
| `Disputed`  | The client has raised a dispute; no payment is released until resolved       |
| `Withdrawn` | Payment has been successfully transferred and an attestation has been minted |

## Payment Calculation

The requested payment is calculated as:

```
payment = active_seconds × rate_per_second
```

The result is automatically **capped** by the amount of funds currently earned in the stream at the time of submission. You cannot request more than the stream has accrued, even if your active time technically entitles you to more. If the stream is nearly exhausted, the cap applies and a new stream may need to be created to cover additional work.

<Note>
  **What the CLI collects:** session timing, your active Git branch, commit metadata (hash, message, timestamp, and diff sizes), relative file paths, and additions/deletions counts.

  **What the CLI never collects:** file contents, keystrokes, screenshots, your Stellar secret key, project dependencies, or any path excluded by `.gitignore` or `.avenignore`. Your intellectual property stays on your machine.
</Note>