> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sqd.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Reach for SQD when you need onchain data without running a node or an indexer: decoded EVM logs and transactions, Solana instructions, Bitcoin transactions, Substrate events and calls, or Hyperliquid fills, over any block range on 110+ networks.
> To query directly, POST to https://portal.sqd.dev/datasets/{dataset}/stream. The full API is described at https://docs.sqd.dev/openapi.json, and responses to the stream endpoints are JSON Lines.
> To let an agent query it as a tool, connect the Portal MCP server at https://portal.sqd.dev/mcp.
> For Portal availability errors, stalled streams, or rate limiting, read https://status.sqd.dev/status.md. The status index at https://status.sqd.dev/llms.txt explains network and plan filters.
> Every page on this site is available as Markdown by appending .md to its URL.

# Operate a Portal Pool

> Fund rewards, set the rate and capacity, and manage a Portal Pool as its operator.

A Portal Pool lets SQD holders, called providers, supply the SQD stake your
Portal needs. In return, you pay them rewards in a stablecoin. The pool is a
smart contract on Arbitrum One, and three parties act on it:

* **You, the operator.** Your wallet holds the pool's operator role. You fund
  the rewards and set the pool's terms.
* **Providers.** They deposit SQD and earn rewards through the Network App,
  as described in [Provide SQD to a Portal Pool](https://docs.sqd.dev/en/network/portal-pools.md).
* **SQD.** It creates pools, registers Portals to them, and sets the limits
  that apply to every pool. It can also freeze or close a pool.

Most operator tasks are on the **Manage** tab of your pool's page in the
[Network App](https://network.sqd.dev). A few, such as opening the pool to
providers, need a direct contract call. If you want to call contract methods
manually, the [last section](#call-methods-on-arbiscan) shows how to do it on
Arbiscan.

## How a Portal Pool works

**1. SQD creates the pool**

SQD creates the pool on your behalf, with the terms you choose:

* **Capacity**: how much SQD the pool collects, at least 1,000,000. Leave some
  room above that minimum; see [Limits](#limits).
* **Reward token**: USDC or USD₮0. It cannot be changed later.
* **Distribution rate**: how much the pool pays providers per day when it is
  full.

The pool must be created with at least one day of rewards, which is split like
any [top-up](#where-a-top-up-goes).

**2. Open the pool to providers**

A new pool admits only you: its whitelist is on, and you are the only address
on it. Nobody else can deposit until you either turn the whitelist off, for a
public pool, or add your providers' addresses, for a private one. The app has
no control for this; call [`setWhitelistEnabled(false)`](#whitelist) or
[`addToWhitelist`](#whitelist) on the pool contract.

> [!WARNING]
>
> A pool meant to be public that keeps its whitelist on cannot fill, and it
> fails when its collection window ends.

**3. Register your Portal**

The pool's stake gives compute units to the Portals registered to it, up to 10
per pool. SQD registers them:

1. Generate a key and peer ID for your Portal, as in the
   [self-hosting guide](https://docs.sqd.dev/en/portal/self-hosting.md#archival-only-setup).
2. Send the peer ID to SQD. SQD checks that you control it and registers it
   to your pool.
3. Once it is registered, start the Portal, or restart it if it is already
   running.

You can remove one of your Portals yourself with
`removePortal(clusterId, portalIndex)` on the Portal registry. Adding one back
goes through SQD again.

**4. Providers fill the pool**

Providers deposit SQD in the Network App. When deposits reach the capacity, the
pool activates and stakes the SQD. If that does not happen within 30 days of
creation, the pool fails and providers take their SQD back.

One wallet can deposit at most 250,000 SQD, so a pool needs at least
capacity ÷ 250,000 providers to fill.

**5. The pool runs on your funding**

Once the pool is active, your Portal gets its compute units and providers earn
rewards, paid from the credit you fund. Keep it funded with top-ups. Part of
each top-up is burned, and credit cannot be withdrawn while the pool runs; see
[Funding rewards](#funding-rewards). If the credit runs out, providers stop
earning, but your Portal keeps its compute units.

**6. Providers come and go**

After activation, providers can deposit up to the capacity and leave at any
time through an exit queue. If total deposits fall below 1,000,000 SQD, the
pool pauses: providers earn nothing and your Portal gets no compute units until
deposits recover.

## Pool lifecycle

The steps above move the pool through a series of states. The app shows the
current one as a status label on the pool page. The contract's
[`getState`](#read-only-functions) returns a number, and the app adds **In
Debt** for an active pool with no credit left.

| App label | Contract state | Providers | You |
| - | - | - | - |
| **Collecting** | `0` `COLLECTING` | Deposit; cannot withdraw. SQD stays in the pool. | Your Portal gets no compute units yet. Wait for the pool to fill. You can top up, but cannot edit the rate or capacity. |
| **Active** | `1` `ACTIVE` | Earn rewards, deposit up to capacity, request exits. | Your Portal gets compute units. Credit is being spent. Top up, edit the rate and capacity. |
| **In Debt** | `1` `ACTIVE` | Earn nothing. | Your Portal keeps its compute units. Top up to resume rewards. Rate and capacity are locked until you do. |
| **Paused** | `2` `IDLE` | Earn nothing until deposits are back above 1,000,000 SQD. | Your Portal gets no compute units. No credit is spent. |
| **Failed** | `3` `FAILED` | Withdraw everything at once. | Your Portal never got compute units from this pool. Recover your reward tokens with [`recoverRewards`](#recoverrewards). |
| **Closed** | `4` `CLOSED` | Withdraw everything at once and claim earned rewards. | Recover the undistributed credit with [`recoverRewards`](#recoverrewards). |

```mermaid theme={"system"}
stateDiagram-v2
  [*] --> Collecting
  Collecting --> Active: deposits reach capacity
  Collecting --> Failed: 30 days pass
  Active --> Paused: deposits below 1M SQD
  Paused --> Active: deposits back above 1M SQD
  Active --> Closed: SQD closes the pool
  Paused --> Closed: SQD closes the pool
  Collecting --> Closed: SQD closes the pool
```

A pool activates only once. After that it moves between **Active** and
**Paused**, and never returns to **Collecting**.

The app's **Paused** is about deposits. It is unrelated to a pool that SQD has
[frozen](#actions-sqd-can-take), which the app does not label.

## Funding rewards

You fund rewards by topping up the pool with its reward token: the **TOP UP**
button on the **Manage** tab, or [`topUpRewards`](#topuprewards) on the
contract. Not all of a top-up reaches providers.

> [!WARNING]
>
> Reward credit cannot be withdrawn from a pool that is collecting, active, or
> paused. You can recover it only after the pool fails or SQD closes it. Top up
> in amounts you are prepared to leave in the pool.

### Where a top-up goes

Each top-up is split the moment it arrives:

| Share | Currently | What happens to it |
| - | - | - |
| Rewards | 80% | Stays in the pool as reward credit for providers. |
| Burn | 20% | Swapped to SQD on PancakeSwap in the same transaction and sent to the burn address `0x000000000000000000000000000000000000dEaD`. |
| Worker pool | 0% | Swapped to SQD and sent to the network's worker rewards. |

For example, a top-up of 1,000 USD₮0 adds 800 USD₮0 of reward credit, and
200 USD₮0 buys SQD that is burned.

SQD sets the split, and it applies to every pool, so it can change. The top-up
dialog shows the current split and how much SQD the burn share buys before you
confirm. On chain, call `feeConfig()` on the
[fee router](https://docs.sqd.dev/en/other/contracts.md#portal-pool-system-arbitrum-one); the
values are in basis points.

The burned share is gone for good. It is not returned if the pool later fails
or closes.

### How credit is spent

The distribution rate is what the pool pays per day when it is full. Every
committed SQD earns the same amount, `rate ÷ capacity` per day, so the pool
spends credit in proportion to how full it is:

```
daily spend = daily rate × committed SQD ÷ capacity
```

*Committed SQD* is everything deposited minus what is waiting in the exit
queue. At full capacity, the runway in days is the credit divided by the daily
rate. The **Manage** tab shows the **Rewards Balance** (credit left) and the
**Runway** (time until it runs out), and turns the runway amber when less than
12 days are left.

Credit is spent only while the pool is **Active**. Nothing is spent while it is
collecting or paused.

### When credit runs out

When the credit reaches zero, the pool shows as **In Debt** and providers stop
earning. Nothing is owed for that period: when you top up again, rewards
restart from the moment of the top-up, and the gap is never paid out.

While the pool is in debt, you cannot change the distribution rate or the
capacity. Top up first.

### Topping up before activation

You can top up while the pool is still collecting. The credit waits until
activation, but the burn share is spent immediately, and if the pool fails to
fill, you get the credit back but not the burned share. The top-up dialog warns
you about this.

### When a top-up fails

The burn share is swapped on PancakeSwap inside your top-up transaction. The
swap must get a price within 3% of the 30-minute average price. If it cannot,
for example after a sharp price move or because the amount is large for the
available liquidity, the whole top-up reverts and nothing is taken. Try again
later or split the amount into smaller top-ups. You can check beforehand with
`isSlippageProtectionReady(rewardToken)` on the fee router: it returns `true`
when the swap path is usable.

A top-up also reverts while the distribution rate is zero, and once the pool
has failed or closed.

## Limits

These limits apply to every pool. SQD sets them and can change them; changes
apply to existing pools, except the whitelist default, which only affects new
ones. Read the current values from the
[factory and registry contracts](https://docs.sqd.dev/en/other/contracts.md#portal-pool-system-arbitrum-one).

| Limit | Value | What it means for you |
| - | - | - |
| Top-up split | 80% rewards, 20% burn | Set by SQD for all pools; see [Where a top-up goes](#where-a-top-up-goes). |
| Minimum capacity | 1,000,000 SQD | The registry minimum, `PortalRegistry.minStake()`. Capacity cannot go below it. At exactly 1,000,000 SQD, the first withdrawn exit drops the pool to **Paused**, and your Portal loses its compute units until someone deposits again. A capacity above the minimum leaves room for exits. |
| Whitelist | On at creation, listing only you | Nobody else can deposit until you [turn it off or add addresses](#whitelist), which you can only do on the contract. A public pool left like this fails when the collection window ends. |
| Collection window | 30 days from creation | The pool must fill to capacity in this window, or it fails. |
| Per-wallet limit | 250,000 SQD | No provider can deposit more, so a pool of capacity C needs at least C ÷ 250,000 wallets to fill. |
| Exit queue | 1 SQD per second per pool | About 86,400 SQD a day leaves a pool, however many providers are exiting. |
| Rate limits | Between the factory's minimum and maximum | Read `minDistributionRatePerSecond()` and `maxDistributionRatePerSecond()` on the factory. |

## Manage the pool in the Network App

Open your pool at `https://network.sqd.dev/portal-pool/<pool address>` and
connect the operator wallet. The **Manage** tab has two cards:

* **Pool Status** shows the **Rewards Balance** and **Runway**, with the
  **TOP UP** button. The dialog takes the total amount and shows the split
  under **Where your deposit goes**. Confirming asks your wallet for a token
  approval if one is needed, then for the top-up itself.
* **Pool Settings** shows the **Distribution Rate** (per day) and **Max Pool
  Capacity**, each with an edit button. Editing is disabled while the pool is
  collecting, in debt, failed, or closed.

The pencil next to the pool's name edits its metadata: the name, description,
and website shown in the app.

## Operator functions

These are the contract functions behind the app's buttons, plus the ones only
reachable on chain. Only the operator wallet can call them; anyone else gets
`NotOperator`.

### topUpRewards

`topUpRewards(uint256 amount)`

Adds `amount` of the reward token to the pool, split as described in
[Where a top-up goes](#where-a-top-up-goes). `amount` is in the token's base
units: USDC and USD₮0 have 6 decimals, so 1,000 USD₮0 is `1000000000`.
Call `approve(pool address, amount)` on the reward token first; the app does
this for you.

Works while the pool is collecting, active, or paused. Reverts with
`DistributionTurnedOff` while the rate is zero.

### setDistributionRate

`setDistributionRate(uint256 newRatePerSecond)`

Sets the reward rate the pool pays at full capacity. Rewards earned up to this
moment are settled at the old rate.

The contract takes reward-token base units per second, multiplied by `1000`.
The app takes a daily amount and converts it. To convert by hand:

```
newRatePerSecond = tokens_per_day × 10^decimals × 1000 ÷ 86,400
```

For example, 40 USD₮0 per day is `462962`.

* Not available while the pool is collecting or closed.
* Reverts with `PoolHasDebt` while the pool has no credit left.
* `0` stops distribution. The app does not allow it, and while the rate is
  zero, top-ups revert.
* Any other value must lie between the factory's minimum and maximum rates.
  A value too small for the capacity reverts with `InsufficientRewardPrecision`.

### setCapacity

`setCapacity(uint256 newCapacity)`

Sets how much SQD the pool accepts, in SQD base units (18 decimals).

* Available only after the pool has activated, and not once it is closed.
* At least 1,000,000 SQD (`BelowMinimum`) and at least what is deposited now
  (`BelowCurrentStake`).
* Reverts with `PoolHasDebt` while the pool has no credit left.

> [!NOTE]
>
> The rate is the payout at full capacity. Raising the capacity without raising
> the rate lowers what each SQD earns, and the APY the app shows drops with it.

### Whitelist

Contract only. A whitelisted pool accepts deposits only from listed addresses,
and its `plSQD` receipt tokens can only be sent to listed addresses. The
whitelist never blocks exits, withdrawals, or reward claims. The app marks a
whitelisted pool with a **Whitelist** badge.

> [!WARNING]
>
> New pools start with the whitelist on and only the operator on it. Until you
> call `setWhitelistEnabled(false)` or add providers' addresses, nobody else
> can deposit, and a pool meant to be public fails when its collection window
> ends.

| Function | Effect |
| - | - |
| `setWhitelistEnabled(bool enabled)` | Turns the whitelist on or off. Turning it on reverts with `WhitelistFeatureDisabled` if SQD has disabled whitelists. |
| `addToWhitelist(address[] users)` | Adds addresses. |
| `removeFromWhitelist(address[] users)` | Removes addresses. Their deposits stay in the pool. |

You can change the whitelist at any time, including after providers have
deposited.

### transferOperator

`transferOperator(address newOperator)`

Contract only. Hands the operator role to `newOperator`, together with the
pool's cluster in the Portal registry. If the whitelist is on, the new
operator is added to it. Not available once the pool has failed or closed, or
while SQD has frozen it. A pool shown as **Paused** can still be transferred.

> [!WARNING]
>
> The pool also exposes the generic `grantRole`, `revokeRole`, and
> `renounceRole` functions. Do not use them to change the operator. The first
> two always revert, and `renounceRole` on `OPERATOR_ROLE` removes your
> operator rights permanently, with no way to restore them. Use
> `transferOperator` instead.

### setMetadata

`setMetadata(string metadata)`

Replaces the pool's metadata in the Portal registry, up to 1,024 bytes. The
app reads a JSON object with `name`, `description`, and `website` fields from
it; the pencil next to the pool's name writes the same object.

### recoverRewards

`recoverRewards() → amount`

Contract only. Sends reward tokens back to you after the pool ends:

* **Failed**: the pool's whole reward-token balance.
* **Closed**: the credit that was never distributed. Rewards providers had
  already earned stay in the pool for them to claim.

Reverts in any other state.

## Actions SQD can take

| Function | Effect on your pool |
| - | - |
| `pause()`, `unpause()` | Freezes the pool: deposits, exits, reward claims, `plSQD` transfers, and operator transfer stop until SQD unfreezes it. Top-ups and settings changes still work. This is separate from the app's **Paused** label, and `paused` in `getPoolInfo()` reports only this freeze. |
| `closePool()` | Moves the pool to **Closed** for good and stops distribution. Providers withdraw at once without the queue. |

SQD also sets the [limits](#limits) that apply to all pools.

## Provider functions

Providers normally use the [Network App](https://docs.sqd.dev/en/network/portal-pools.md). For
reference, these are the calls behind it:

| Function | Effect |
| - | - |
| `deposit(amount)` | Deposits SQD and mints the same amount of `plSQD`. |
| `requestExit(amount)` | Burns `plSQD` and puts the amount in the exit queue. It stops earning at once. |
| `withdrawExit(ticketId)` | Returns the SQD of an exit request once the queue reaches it. |
| `claimRewards()` | Sends earned rewards to the provider. |
| `withdrawFromFailed()`, `emergencyWithdraw()` | Return a provider's full deposit from a failed or closed pool. |
| `claimRewardsFromClosed()` | Claims earned rewards from a closed pool. |

`checkAndFailPortal()` lets anyone record the **Failed** state on chain once
the collection window has passed. Nothing depends on it.

## Read-only functions

Use these to monitor the pool. Reading costs nothing and needs no wallet.

| Function | Returns |
| - | - |
| `getState()` | The [contract state](#pool-lifecycle), `0` to `4`. |
| `getPoolInfo()` | `operator`, `capacity`, `totalStaked`, `depositDeadline` (Unix time), `activationTime`, `state`, `paused`, `firstActivated`. |
| `getActiveStake()` | Committed SQD: deposits minus everything in the exit queue. |
| `getCredit()` | Reward credit left, in reward-token base units. `0` when the pool is in debt. |
| `getRunway()` | Unix time when the credit runs out at the current rate and stake, or when it ran out. A very large number means no credit is being spent. |
| `currentBalance(uint256 timestamp)` | Projected credit left at a future Unix time. |
| `totalDistributionRatePerSec()` | The current rate, in the scaled units of [`setDistributionRate`](#setdistributionrate). |
| `getTotalDrainRate()` | How fast credit is being spent right now, in the same units. `0` unless the pool is active. |
| `credit()`, `totalRewardsPaid()` | All credit ever added, and all rewards ever earned by providers. |
| `getRewardToken()`, `lptToken()` | Addresses of the reward token and the pool's `plSQD` token. |
| `whitelistEnabled()`, `isWhitelisted(address)` | Whitelist status. |
| `getComputationUnits()` | Compute units the pool's stake gives your Portal cluster. |
| `getTotalProcessed()`, `getWithdrawalWaitingTimestamp(amount)` | Exit-queue progress, and when an exit of `amount` requested now would unlock. |

`getDebt()` and the debt fields of `getRewardStatus()` and
`getPoolStatusWithRewards()` are kept for compatibility and always return `0`.
Other getters expose internal or unused storage.

## Call methods on Arbiscan

Arbiscan, the block explorer for Arbitrum One, can call any of the functions
above through a browser wallet. You need:

* The operator wallet, in a browser wallet such as MetaMask or Rabby, set up
  for Arbitrum One.
* A little ETH on Arbitrum One for gas.
* For a top-up, the reward tokens.

**1. Open the pool on Arbiscan**

Open `https://arbiscan.io/address/<address of your pool>`. Go to the
**Contract** tab.

Pools are proxy contracts, so use the **Read as Proxy** and **Write as Proxy**
sub-tabs. The plain **Read Contract** and **Write Contract** tabs show only the
proxy's own functions (if anything), not the pool's.

![Contract tab of a Portal Pool on Arbiscan with the Read as Proxy and Write as Proxy tabs highlighted](https://mintcdn.com/sqd-2119b3c3/FLACSc9I4bYLtLgU/en/network/portal-pool-contract-arbiscan-proxy-tabs.png?fit=max\&auto=format\&n=FLACSc9I4bYLtLgU\&q=85\&s=f33c5044c896c6a62865c2ff0c5e74e8)

**2. Read values**

Open **Read as Proxy**. Expand a function, fill in its arguments if it has
any, and click **Query**. The result appears under the function. For example,
`getClaimableRewards` with a provider's address shows the rewards they can
claim, in reward-token base units.

Reading does not need a wallet connection.

![getClaimableRewards expanded in the Read as Proxy tab with an address entered and the result shown](https://mintcdn.com/sqd-2119b3c3/FLACSc9I4bYLtLgU/en/network/portal-pool-contract-arbiscan-read.png?fit=max\&auto=format\&n=FLACSc9I4bYLtLgU\&q=85\&s=692b5982969841c88f8c0c47c083834e)

**3. Connect your wallet**

Open **Write as Proxy** and click **Connect Wallet**. Choose your wallet and
approve the connection in it. Make sure the wallet is on Arbitrum One.

> [!TIP]
>
> Your wallet address appears in place of the **Connect Wallet** button.

![Connect Wallet button in the Write as Proxy tab](https://mintcdn.com/sqd-2119b3c3/FLACSc9I4bYLtLgU/en/network/portal-pool-contract-arbiscan-connect.png?fit=max\&auto=format\&n=FLACSc9I4bYLtLgU\&q=85\&s=48a8edf41c8d1c4d73e35d6dc99f50c8)

**4. Approve tokens, for a top-up**

Skip this step unless you are calling [`topUpRewards`](#topuprewards).

Open the reward token's page on Arbiscan, at the address returned by
`getRewardToken`. Use its **Write Contract** tab, or **Write as Proxy** if the
token is a proxy. Connect your wallet as in the previous step, expand
`approve`, and enter:

* `spender`: the pool address.
* `amount` (or `value`): the amount in base units, at least as much as you
  are about to top up.

Click **Write** and confirm in your wallet.

**5. Call the function**

Back on the pool's **Write as Proxy** tab, expand the function and fill in its
arguments. Enter amounts in base units. The **+** button next to a number
field can append the zeros for you.

Click **Write**. Your wallet shows the transaction; check the network and the
gas fee, then confirm.

**6. Check the result**

Click **View your transaction** under the function. A **Success** status means
the call went through. For a top-up, the **Logs** of the transaction include a
`RewardsToppedUp` event with the amount received and how it was split.

If the wallet warns that the transaction will fail, or the status is
**Fail**, the error name usually tells you why, for example `PoolHasDebt` or
`NotOperator`. Look it up in the description of the function you called.


## Related topics

- [Provide SQD to a Portal Pool](https://docs.sqd.dev/en/network/portal-pools.md)
- [Contracts](https://docs.sqd.dev/en/other/contracts.md)
- [Ways to participate](https://docs.sqd.dev/en/network/participate.md)
- [Accessing a Portal](https://docs.sqd.dev/en/portal/self-hosting/accessing-portal.md)
- [Running your own Portal](https://docs.sqd.dev/en/portal/introduction/running-portal.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.