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

# Stellar lending deployment

> Build WASM artifacts, deploy governance, bring up the controller and central pool, list markets through the timelock, and unpause.

Build, deploy, and bring up the protocol: governance first, then the controller, then the single central pool, then each market through timelocked proposals, then `unpause`.

The operator surface is the repo `Makefile` (wrapping the `stellar` CLI) plus `configs/script.sh`. The same sequence applies to testnet and mainnet; substitute `testnet` or `mainnet` for `<network>` below.

## Source of truth

| File                           | Purpose                                                                                                 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `configs/networks.json`        | Per-network RPC, passphrase, governance, controller, pool, aggregator, timelock delay, and WASM hashes. |
| `configs/mainnet_markets.json` | Mainnet market definitions (asset, rate model, risk config).                                            |
| `configs/testnet_markets.json` | Testnet market definitions.                                                                             |
| `configs/spokes.json`          | Spoke definitions and per-asset spoke memberships per network.                                          |
| `configs/blend_pools.json`     | Approved Blend pool addresses for migration.                                                            |
| `Makefile`                     | Build, deploy, configure, market setup, and inspection targets.                                         |

## Prerequisites

* The `stellar` CLI and `jq`.
* A Rust toolchain matching `rust-toolchain.toml`.
* A funded signing identity (default `deployer`), or `SIGNER=ledger` for a ledger-backed signer.

## Build artifacts

```bash theme={"system"}
make build              # stellar contract build — all contracts
make deploy-artifacts   # optimize + stage stripped WASM under artifacts/wasm/deploy/
```

`make deploy-artifacts` produces `governance.wasm`, `controller.wasm`, and `pool.wasm` for upload.

## Deploy and bring-up order

The order is load-bearing. Governance deploys first. The controller starts **paused** at construction with governance as owner. The pool deploys **once** for the whole protocol. Each asset registers on that shared pool through timelocked proposals.

`make setup-<network>` runs the full sequence. The steps below show what each phase does.

<Steps>
  <Step title="Deploy governance">
    Uploads pool, controller, and governance WASM, then deploys governance with `__constructor(admin, min_delay)`. Governance grants `PROPOSER`, `EXECUTOR`, `CANCELLER`, and `ORACLE` to the admin. Writes governance id and timelock delay to `configs/networks.json`.

    ```bash theme={"system"}
    make deploy-<network>
    ```
  </Step>

  <Step title="Deploy the controller">
    Governance calls `deploy_controller(controller_wasm_hash)` immediately (one-time, owner-gated). The controller constructor sets governance as owner, grants `ORACLE` to governance, and **pauses** the contract.

    ```bash theme={"system"}
    # bundled in make deploy-<network>
    stellar contract invoke --id <governance> --network <network> \
      -- deploy_controller --wasm-hash <controller_wasm_hash>
    ```
  </Step>

  <Step title="Set pool template and deploy the central pool">
    Schedule and execute pool template registration, then pool deployment. Each step is timelocked in production.

    ```bash theme={"system"}
    # propose_set_pool_template → execute
    # propose_deploy_pool → execute   // once; repeat reverts #5 PoolAlreadyDeployed
    ```

    `configure-controller` bundles template, pool deploy, aggregator, accumulator, and ORACLE role grant.
  </Step>

  <Step title="Register each market on the shared pool">
    Per asset, governance schedules:

    1. `propose_approve_token`
    2. `propose_create_liquidity_pool`
    3. `propose_configure_market_oracle`
    4. `propose_edit_asset_config`

    Each proposal executes after the timelock delay. `create_liquidity_pool` registers the hub asset on the **existing** central pool. Price reads work only after `AssetOracle(asset)` is configured.

    ```bash theme={"system"}
    make setupAll NETWORK=<network>   # driven by configs/script.sh
    ```

    `create_liquidity_pool` reverts with `#30 PoolNotInitialized` if `deploy_pool` has not run, `#35 TokenNotApproved` if the token was not approved, and `#2 AssetAlreadySupported` if already listed.
  </Step>

  <Step title="Configure spokes and Blend pools">
    Spokes are configured from `configs/spokes.json`:

    ```bash theme={"system"}
    propose AdminOperation::AddSpoke → execute
    propose AdminOperation::AddAssetToSpoke per hub asset → execute
    ```

    Blend migration pools are approved from `configs/blend_pools.json`:

    ```bash theme={"system"}
    propose_approve_blend_pool → execute
    ```
  </Step>

  <Step title="Unpause">
    Turn the protocol live only after the pool is deployed and every market is `Active`.

    ```bash theme={"system"}
    stellar contract invoke --id <governance> --network <network> \
      -- unpause
    ```

    Unpause is immediate through the governance owner. It forwards to the paused controller.
  </Step>
</Steps>

<Note>
  `make setup-<network>` chains: `deploy-<network>` → `configure-controller` → market, spoke, and Blend setup → `unpause`. Run individual targets only for partial deploys or recovery.
</Note>

## Verification gates

Mainnet launch requires the acceptance matrix in the architecture reference: workspace tests, integration harness, fuzz targets, Certora profiles, external audit closure, 14-day testnet soak, and pause drill. Initial launch caps (ADR 0009): USD 250,000 total TVL, USD 100,000 total borrow, USD 100,000 per-market supply, USD 50,000 per-market borrow.

## Upgrades

| Target                               | Path                                     | Effect                                       |
| ------------------------------------ | ---------------------------------------- | -------------------------------------------- |
| `make <network> upgradePoolTemplate` | `propose_set_pool_template` → execute    | Upload and register new pool WASM template.  |
| `make <network> upgradePools`        | `propose_upgrade_pool` → execute         | Upgrade the single central pool in place.    |
| `make <network> upgradeController`   | `propose_upgrade_controller` → execute   | Upgrade controller WASM (auto-pauses first). |
| `make <network> upgradeAll`          | template → controller → pool → `unpause` | Full upgrade then re-enable.                 |

Governance self-upgrade uses `propose_governance_upgrade` → `execute_governance_upgrade`.

## Smoke tests

```bash theme={"system"}
make <network> deployFlashReceiver
make <network> fundFlashReceiver
make <network> testFlashReceiver
```

Confirm market state with `make <network> getAllMarkets` and `make <network> getAllIndexes`.

## Next

<CardGroup cols={2}>
  <Card title="Governance" icon="landmark" href="/stellar-lending/dev/governance">
    Timelock roles and the propose/execute lifecycle.
  </Card>

  <Card title="Configuration" icon="sliders" href="/stellar-lending/dev/configuration">
    Validation rules for risk, oracle, and spoke parameters.
  </Card>

  <Card title="Addresses" icon="address-book" href="/stellar-lending/dev/addresses">
    Deployed contract addresses per network.
  </Card>
</CardGroup>