Smart contracts

Deploys a new Residency contract with the caller as its host. Each residency is its own contract, so funds from different stays never mix.

• The app only lists residencies deployed from an approved proposal: the server decodes the event and checks the metadata hash, dates and seats against the proposal before recording it.
• The new address is appended to the factory's list, so every residency ever launched can be enumerated onchain.

Reverts: InvalidParams (from the Residency constructor) if the dates or seat counts break the rules below.

Emits: ResidencyCreated(residency, host, metadataHash, startTime, endTime, deadline, minSeats, maxSeats)

How many residencies the factory has deployed.

The residency deployed at position index (0-based, in launch order). Reverts past the end of the list.

The USDC token every residency from this factory accepts. Fixed at factory deploy.

Approves a wallet for a specific bed at a specific price (USDC with 6 decimals, so 1,400 USDC is 1400000000). Approval is what lets the member stake.

• Re-approving a member who hasn't paid yet moves them to the new bed and price and frees their old bed.
• One bed holds one member. Approving someone for a bed another wallet holds reverts.
• The host can approve more people than maxSeats. Seats go to whoever pays first.

Reverts: NotHost, WrongStatus · InvalidMember: zero address or zero price · AlreadyStaked: the member has already paid · BedTaken(bedId, holder): another wallet holds that bed

Emits: Approved(member, bedId, price)

Withdraws an approval that hasn't been paid yet and frees the bed. A member who has staked can't be revoked.

Reverts: NotHost, WrongStatus · NotApproved: nothing to revoke · AlreadyStaked: the member has paid

Emits: Revoked(member, bedId)

Calls the residency off before the deadline. The status becomes Failed permanently, and every staker can claim a full refund.

Reverts: NotHost, WrongStatus

Emits: Cancelled()

Sends amount USDC from the residency to the host to pay for the stay, recording the sha256 of the receipt file and a short note onchain.

• The contract doesn't check the receipt. It records the hash so anyone can match the uploaded file against it. The app rejects receipt uploads whose hash doesn't match the Withdrawn event.
• The host can withdraw any amount up to the full balance, in one or more withdrawals, from the moment the deadline passes. See the trust model below.
• The note is capped at 280 bytes.

Reverts: NotHost, WrongStatus · InvalidAmount: zero, or more than the balance · NoteTooLong: note over 280 bytes

Emits: Withdrawn(amount, receiptHash, note)

Ends an Active residency. The balance at that moment is frozen as closedBalance and each staker can claim their share of it.

• Anyone can close after the end date, so a host who disappears can't lock the leftovers.
• After close there are no more withdrawals.

Reverts: WrongStatus · CloseNotAllowed: a non-host called before endTime

Emits: Closed(closedBalance)

Sends everything still in the contract to the host: shares nobody claimed, rounding dust, and USDC sent here by mistake. Members have 180 days after closing to claim before their share can be swept.

• After a sweep, claimable() returns 0 and claim() reverts for anyone who hadn't claimed.
• A Failed residency can never be swept. Every refund stays claimable forever.

Reverts: NotHost, WrongStatus · SweepTooEarly(availableAt): less than 180 days since close · InvalidAmount: nothing to sweep

Emits: Swept(amount)

Offers the host role to another wallet. Nothing changes until that wallet calls acceptHost(). Pass the zero address to cancel a pending offer.

• Use it to rotate a host key, or to hand a residency to a co-organizer.

Reverts: NotHost

Emits: HostTransferStarted(currentHost, newHost)

Completes a host transfer. The caller becomes the host, with every host power and future withdrawals, and the previous host loses them. The two steps mean a typo'd address can never become the host.

Reverts: NotPendingHost: the caller isn't the offered wallet

Emits: HostTransferred(previousHost, newHost)

Pays your approved price into the residency and takes a seat. You need to approve the residency to spend that much USDC first. The app does this as step 1 of 2.

• expectedPrice is the price you saw and agreed to. If the host re-approved you at a different price before your transaction landed, stake reverts with PriceChanged instead of charging you the new amount.
• Once staked, you can't be revoked or moved to another bed, and you can't unstake. Your way out is a refund if the residency fails or is cancelled.

Reverts: WrongStatus: past the deadline, or cancelled · NotApproved, AlreadyStaked · PriceChanged(currentPrice): your approved price isn't expectedPrice · ResidencyFull: maxSeats already paid

Emits: Staked(member, bedId, price, seatNumber)

Pays out whatever claimable(you) returns, once. Full refund if Failed; your pro-rata share of leftovers if Closed.

Reverts: NothingToClaim: not staked, already claimed, or the residency is Open or Active

Emits: Claimed(member, amount)

The current state, computed from the clock and flags rather than stored: Closed if closed; Failed if cancelled; Open before the deadline; then Active if seatCount ≥ minSeats, otherwise Failed.

A wallet's record: approved, staked, claimed, bedId and price. The app uses staked to gate who can download receipts.

What claim() would pay this wallet right now. Failed: the full price paid. Closed: closedBalance × price ÷ totalStaked, until the host sweeps. Otherwise, or if already claimed: 0.

The residency's current USDC balance.

Which wallet holds a bed, approved or staked. Zero address if the bed is free.

The wallet offered the host role by transferHost(). Zero address if no transfer is pending.