Factory interface

Shape of the contract

One contract, no inheritance, no libraries, no proxy. Access control is three address variables and three modifiers rather than a role registry, because there are exactly three privileged callers and a registry would only make them harder to read off the chain.

address public owner;         // cold key: roles, pause, cap, rescue
address public pendingOwner;  // owner-elect, until it accepts
address public relayer;        // may call mintFor, nothing else
address public distributor;    // may call creditBatch, nothing else

uint256 public maxPerWallet = 25;
uint256 public constant MAX_PER_WALLET_CEILING = 100;
bool    public paused;

uint256 public outstanding;    // sum of every node balance

A node is a struct, not a token. There is no ownerOf, no transferFrom and no approval surface, so a node cannot be sold or moved once minted. See Node model.

struct Node {
    address owner;
    uint64  createdAt;
    uint128 balance;         // withdrawable right now
    uint128 totalReceived;   // credited over the node's whole life
    uint128 totalWithdrawn;
}

Minting

function mintFor(address to, bytes32 paymentRef)
    external
    onlyRelayer
    returns (uint256 id);

Not payable, because the contract never receives the purchase money. Payment is a plain transfer to the payments wallet, and paymentRef is that transfer’s transaction hash. The relayer sends this call and pays its gas.

paymentRefUsed[paymentRef] is set before anything else, so one payment backs exactly one node. That mapping is the reason the reference in the log is evidence rather than decoration. See Settlement.

Crediting

function creditBatch(uint256[] calldata ids, uint256[] calldata amounts)
    external
    payable
    onlyDistributor;

Payable, and msg.value must equal the sum of amounts exactly. The ETH that backs the balances arrives in the same call that records them, so a balance can never exist unbacked.

The sum is checked before any storage is touched, so a malformed batch costs the caller memory-only gas instead of one write per node. It is not pausable: pausing stops sales, not payouts.

Withdrawing

function withdraw(uint256 id, address to) external;

function withdrawAll(address to) external returns (uint256 amount);

These are the only two functions an ordinary user ever calls, and they are callable by the node’s owner and by nobody else. There is no amount argument: a withdrawal always moves the node’s whole balance.

Both zero the balances and update outstanding before sending, and both carry nonReentrant on top of that. withdrawAll skips nodes with a zero balance rather than reverting on them, so a wallet holding a mix of credited and uncredited nodes still sweeps in one transaction. Neither reads paused.

Reads

Every one of these is view and free to call.

Admin

Every function here is onlyOwner except acceptOwnership, fund and receive, and every one of them emits an event, so the entire history of the admin surface is readable from logs.

Every custom error

Fifteen, all of them zero-argument, so a revert is four bytes and a wallet that decodes the ABI can name it exactly. The selector is the first four bytes of the keccak hash of the signature, which is what you will see in raw RPC output when a wallet fails to decode.

Getting the ABI

The ABI this site uses is generated from the compiled artifact and lives in lib/abi.ts, so it cannot drift from the deployed bytecode. To produce it yourself:

cd contracts
forge build
jq .abi out/SitowiseFactory.sol/SitowiseFactory.json

Or take it from the explorer, where the source is verified. Both should match, and if they do not, trust neither and ask why. The events, with their topic hashes, are on Events.