> For the complete documentation index, see [llms.txt](https://alameen.gitbook.io/streamwage/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://alameen.gitbook.io/streamwage/core-concepts.md). # Core concepts ## How the payroll works This section covers the three foundational ideas behind StreamWage: how workers are represented, how they earn over time, and how that earning logic was designed to stay clean across state changes. *** ### Workers Every participant in the payroll is stored as a `Worker` struct mapped to their wallet address. A worker tracks everything needed to compute what they are owed at any point in time, their rate, their timeline, the last time their earnings were settled, their unclaimed balance, and their total lifetime claimed amount. Workers can be active or paused. When a worker is paused, accrual stops. When they are reactivated, accrual resumes from that point forward, time spent paused is never counted. {% hint style="info" %} Pausing a worker always triggers a settlement first, so no earned time is lost at the moment of pause. {% endhint %} *** ### Payment timelines Each worker is assigned one of four timeline types when they are registered. The timeline determines how their earnings are denominated and at what cadence they accrue. Hourly intervalSeconds = 3600 Worker earns a fixed amount every hour. Interval is set automatically. Monthly intervalSeconds = 2592000 Worker earns a fixed amount every 30 days. Interval is set automatically. Custom intervalSeconds = caller-defined Operator provides any interval in seconds. Useful for weekly, bi-weekly, or non-standard pay cycles. Trigger intervalSeconds = 0 No automatic accrual. An operator manually grants a payment amount at any time. Used for bonuses or milestone-based pay. *** ### Accrual : how earnings are calculated Earnings are not streamed continuously in storage. Instead, the contract calculates what a worker is owed at the moment it is needed, on a claim, a pause, a rate change, or any other state transition. This calculation is handled by an internal function called `_settleAndReset`. #### The two-phase settlement Settlement runs in two phases every time it is called: Phase 1 : whole intervals The contract counts how many complete intervals have elapsed since the last checkpoint. Each complete interval adds one full `amountPerInterval` to the worker's accrued balance. The checkpoint advances to the last whole-interval boundary. Phase 2 : fractional remainder The time between the last whole-interval boundary and `block.timestamp` is credited pro-rata. If a worker is halfway through an interval, they receive exactly half the interval's pay. The checkpoint is then set to `block.timestamp`. {% hint style="info" %} After both phases, the checkpoint is always `block.timestamp`. The next settlement always starts from a clean, known position. {% endhint %} *** ### Why it was designed this way Design history The original implementation only settled completed intervals. Partial progress through an in-progress interval was intentionally left as carry-forward drift, a known inaccuracy of at most `intervalSeconds - 1` seconds. That was an acceptable tradeoff for the basic claim flow. The problem surfaced during a review of state transitions: when a worker's rate was changed, the unsettled drift from the old rate was carried forward and effectively valued at the new rate. The math was no longer correct, and the code became harder to reason about. The fix was straightforward ,settle everything before any mutation, including the fractional remainder. Once that was the rule, pausing, rate changes, interval changes, and migrations all became clean. Every state transition starts from a fully settled, zero-drift position. *** ### The settle-before-mutate rule Every function that modifies a worker's state calls `_settleAndReset` first. This is the contract's core invariant. It means: Rate changes apply only to time accrued after the change. Pauses stop accrual without losing the partial interval the worker had already earned. Migrations carry over a fully settled balance with no floating drift attached. Term negotiations always start from a known, accurate accrued balance. {% hint style="info" %} Breaking this rule :- mutating worker state before settling , would silently mis-price earnings. It is not enforced by the type system, it is a discipline that every future modification to the contract must respect. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://alameen.gitbook.io/streamwage/core-concepts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.