> 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/contract-reference.md). # Contract reference ## Function reference All callable functions in `StreamWagePayroll`, grouped by who can call them. Internal functions are documented in the Core Concepts section. ## Owner `onlyOwner` The owner is set at initialization and is the only address that can manage admin roles or transfer ownership. Ownership is a single address, there is no multisig built in at the contract level. ### `initialize(address initialOwner)` `write` Called once by the factory at deployment. Sets the owner and emits `OwnerTransferred`. Cannot be called again, the `initializer` modifier enforces this. ### `transferOwnership(address newOwner)` `write` Transfers ownership to a new address immediately. There is no two-step confirmation, the caller is responsible for providing a correct address. ### `setAdmin(address admin, bool enabled)` `write` Grants or revokes operator privileges for any address. Operators can manage workers and the treasury but cannot transfer ownership or modify other admins. ## Operator `onlyOperator` Operators are the owner plus any address the owner has granted admin status to. They manage the day-to-day operation of the payroll,adding workers, adjusting rates, funding the treasury, and initiating term proposals. ### `fundTreasury()` `payable` Deposits ETH into the treasury. Reverts if no ETH is attached. The contract also accepts ETH directly via its `receive()` fallback without access restriction. ### `addWorker(address, Timeline, uint256, uint256, string)` `write` Registers a new worker. Requires a non-zero address that is not already registered. For time-based timelines, `amountPerIntervalWei` must be non-zero. For `Custom`, a non-zero interval must be provided. Accrual starts immediately from the block of registration. ### `updateWorkerRate(address, uint256)` `write` Changes a worker's pay per interval. Settles all earned time first so the new rate applies only going forward. ### `updateWorkerInterval(address, Timeline, uint256)` `write` Changes a worker's timeline type and interval length. Settles first. If the worker is currently paused, `lastAccruedAt` is also reset to now so the paused gap is not counted as worked time when they resume. ### `updateWorkerMetadata(address, string)` `write` Updates the off-chain metadata string attached to a worker, name, role, or any other arbitrary label. Does not trigger settlement. Purely informational. ### `setWorkerStatus(address, bool)` `write` Pauses or resumes a worker. On pause, settlement runs first so no earned time is lost. On resume, the accrual clock is already clean, no adjustment needed. ### `grantTriggerPayment(address, uint256)` `write` Credits a one-off payment to a `Trigger`-timeline worker. Only valid for workers registered under the `Trigger` timeline. Adds directly to their claimable balance. ### `withdrawExcess(address recipient, uint256 amountWei)` `write` Withdraws surplus ETH from the treasury. Settles all active workers first, then enforces a one-hour minimum reserve before allowing the withdrawal. Reverts with `WithdrawalExceedsSafeLimit` if the amount would breach the reserve floor. ### `setLowTreasuryThreshold(uint256 thresholdSeconds)` `write` Sets the runway threshold below which a `LowTreasury` event is emitted after each claim. Set to zero to disable alerts entirely. ### `setProposalWindow(uint256 durationSeconds)` `write` Updates the default window a worker has to respond to a term proposal. Defaults to 7 days. Applies to all future proposals, existing pending proposals are unaffected. ### `proposeTerms(address, Timeline, uint256, uint256, bool, string)` `write` Opens a term negotiation. Settles the worker, pauses them, and records the proposed terms with an expiry. The `terminateOnReject` flag determines what happens if the worker declines or the window expires. The `proposalNote` is emitted in the event log only, not stored on-chain. ### `cancelProposal(address workerAddr)` `write` Withdraws a pending proposal before the worker has responded. Restores the worker to their prior active status. ## Worker `worker only` Workers are registered addresses. These functions can only be called by the worker themselves, operators cannot claim on a worker's behalf or accept terms for them. ### `claim()` `write` Settles and pays the caller's full claimable balance to their own address. If the treasury cannot cover the full amount, the maximum available is paid and the remainder stays in the worker's accrued balance for a future claim. ### `claimTo(address recipient)` `write` Same as `claim()` but pays out to a specified recipient address instead of the caller. Useful for workers who want to direct earnings to a cold wallet or multisig. ### `acceptTerms()` `write` Accepts a pending proposal. Applies the new rate and timeline, reactivates the worker, and resets the accrual clock from `block.timestamp`. Reverts if the proposal window has expired. ### `rejectTerms()` `write` Rejects a pending proposal. Outcome depends on `terminateOnReject,`the worker is either restored under prior terms or permanently deactivated. Earned balance is never forfeit. Reverts if the proposal window has expired. ### `proposeMigration(address newAddress)` `write` Initiates a wallet migration to a new address. The new address must not already be a registered worker. The migration is not complete until the new address calls `acceptMigration()`. ### `cancelMigration()` `write` Cancels an outgoing migration the caller previously initiated. Clears the pending record and frees the proposed new address. ## Anyone `unrestricted` These functions have no access restriction. Read functions are view-only. `expireProposal` and `acceptMigration` are write functions that anyone may trigger, but they are gated by on-chain conditions. ### `claimable(address workerAddr)` `read` Returns the total amount a worker could claim right now, settled balance plus whole intervals elapsed plus the pro-rata fractional remainder. Mirrors the exact projection that `_settleAndReset` would apply at claim time. ### `treasuryRunway()` `read` Returns the combined pay rate across all active time-based workers, the estimated runway of the free balance at that rate, and the total accrued liability. Returns `type(uint256).max` for runway if no workers are actively accruing. ### `workerRunway(address workerAddr)` `read` Estimates how long the treasury can sustain a specific worker based on their proportional share of the free balance. Returns zero for paused or trigger workers. ### `expireProposal(address workerAddr)` `write` Resolves a proposal that has passed its expiry without a response. Anyone can call this to prevent a worker from being stuck in a permanently paused state. The outcome mirrors rejection under the original `terminateOnReject` flag. ### `acceptMigration(address oldAddress)` `write` Called by the incoming address to complete a migration. Settles the old worker record in full, copies it to the new address, and removes the old one. The full accrual history and any unclaimed balance transfers intact. --- # 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/contract-reference.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.