BlackSwan DeFi Protocol Implementation

This skill guides implementation of a complete on-chain parametric insurance/derivatives system built around existing `Core.sol` and `CoreTypes.sol` contracts, using Foundry and Solidity 0.8.24.

Overview

Implement an orchestrator contract (`Pool.sol`) that bridges Storage and Core, plus ERC1155 Coverage Tickets (CT), ERC20 LP tokens, oracle adapters, withdraw queues, RBC (correlation) checks, full test suite with invariants, and deployment tooling.

Step-by-Step Implementation

1. Repository Setup

Create the Foundry project structure:

```

root/

foundry.toml

remappings.txt

.github/workflows/ci.yml

.prettierrc, .solhint.json, .gitignore, README.md

/contracts

/core — Core.sol, CoreTypes.sol (already exist)

/storage — PoolStorage.sol, StorageCodec.sol, SeriesStorage.sol, QueueStorage.sol

/interfaces — IPool.sol, IPoolAdmin.sol, IOracle.sol, ICToken.sol, ILPToken.sol

/tokens — CToken1155.sol, LPToken.sol

/pool — Pool.sol, PoolAdmin.sol, PoolFactory.sol

/oracle — OracleAdapter.sol, ProportionalModel.sol

/libs — TokenIdLib.sol, AccountingLib.sol, RBCLib.sol, SafeTransferLib.sol, Errors.sol, Events.sol

/script — Deploy.s.sol, CreateSeries.s.sol, Seed.s.sol

/test

/unit — Core_Quote.t.sol, Pool_Buy.t.sol, etc.

/property — Invariants.t.sol

/mocks — MockERC20.sol, MockOracle.sol, etc.

```

Configure `foundry.toml` for Solidity 0.8.24 and set up `remappings.txt`:

```

@openzeppelin/=lib/openzeppelin-contracts/

@aave/=lib/aave-v3-core/

```

2. External Dependencies

Install required libraries:

```bash

forge install OpenZeppelin/openzeppelin-contracts

forge install aave/aave-v3-core

```

Ensure imports work:

3. Implement Interfaces

**`/contracts/interfaces/IPool.sol`** — Define view functions (product, getSeries, previewQuote, utilization, nav, freeCapital, maxLiability) and state-changing functions (buy, settle, mature, redeem, deposit, withdraw).

**`IPoolAdmin.sol`** — Admin functions (pause, unpause, setCooldown, setFees, setOracle, setRBCParams, createSeries).

**`IOracle.sol`** — Oracle adapter interface (eventConfirmed, payoutRatio).

**`ICToken.sol`** — ERC1155 extension (mint, burnFrom, seriesOf, activationStartOf).

**`ILPToken.sol`** — ERC20 extension (mint, burn).

**`Errors.sol` / `Events.sol`** — Shared error and event definitions.

4. Implement Token Contracts

**`CToken1155.sol`** (ERC1155 Coverage Ticket):

**`LPToken.sol`** (ERC20):

5. Implement Library Contracts

**`TokenIdLib.sol`**:

```solidity

function seriesId(bytes32 productId, uint64 maturity) internal pure returns (bytes32)

function ctTokenId(bytes32 seriesId, uint64 activationStart) internal pure returns (uint256)

```

**`RBCLib.sol`**:

**`AccountingLib.sol`** — Thin helpers for NAV and utilization calculations.

**`SafeTransferLib.sol`** — Wrap OZ `SafeERC20` for cleaner code.

6. Implement Pool Orchestrator

**`Pool.sol`** — Core orchestrator with:

**Views**:

**Primary market (`buy`)**:

1. Check cooldown: `require(block.timestamp >= L.cooldownUntil)`

2. Build snapshots (poolBytes, seriesBytes, productBytes)

3. Call `Core.buy(...)`

4. Transfer premium from buyer, transfer fee to treasury

5. Apply deltas via `StorageCodec.applyPoolDelta`, `applySeriesDelta`

6. Mint CT: `tokenId = TokenIdLib.ctTokenId(seriesId, activationStart)`; `CToken1155.mint(receiver, tokenId, notional)`

7. Emit `Bought` event

8. Return `(tokenId, premium)`

**Settlement (`settle`)**:

1. Require `oracle.eventConfirmed(seriesId)`

2. Get `(r, eventTime) = oracle.payoutRatio(seriesId)`

3. Call `Core.settle(...)` with snapshots

4. Apply deltas (sets `paused = true`, `cooldownUntil`)

5. Emit `Settled`

**Maturity (`mature`)**:

1. Require `block.timestamp >= maturity`

2. Call `Core.mature(...)`

3. Apply deltas, emit `Matured`

**Redeem (`redeem`)**:

1. Resolve `seriesId` and `activationStart` from tokenId

2. Ensure series status is `Settled` and `activationStart <= eventTime`

3. Compute payout: `pay = amount * payoutRatioWad / WAD`

4. Burn CT, transfer `pay` to holder

5. Emit `Redeemed`

**LP operations (`deposit`, `withdraw`)**:

**Guards**:

7. Implement Withdraw Queue

Minimal FIFO queue in `QueueStorage.sol` or inline in Pool:

```solidity

struct Request { address lp; uint256 shares; uint256 navAmount; }

mapping(uint256 => Request) q;

uint256 head; uint256 tail;

```

8. Implement Oracle Adapter

**`OracleAdapter.sol`** conforming to `IOracle`:

9. Implement Admin Contract

**`PoolAdmin.sol`** with `AccessControl`:

10. Write Comprehensive Tests

**Unit tests** (`/test/unit`):

**Property-based tests** (`/test/property/Invariants.t.sol`):

**Mocks** (`/test/mocks`):

11. Deployment Scripts

**`Deploy.s.sol`**:

1. Deploy asset (MockERC20 for testnet)

2. Deploy CToken1155, LPToken

3. Deploy Pool with immutable addresses (asset, CT, LP, treasury, oracle)

4. Grant roles (GOVERNOR_ROLE, OPERATOR_ROLE)

5. Set initial fees, RBC params

**`CreateSeries.s.sol`**:

**`Seed.s.sol`**:

12. CI/CD and Tooling

**`.github/workflows/ci.yml`**:

```yaml

```

**Linting**:

13. Documentation

**README.md** should cover:

Key Constraints

Important Notes

Testing Checklist