Plether Protocol Contracts

Plether is a Solidity monorepo for on-chain products that provide bounded, dollar-directional exposure. Spot, options, perpetuals, and the Sepolia perps paymaster are peer Foundry packages under packages/; product-neutral contracts and test utilities live in shared.

The repository root is deliberately a narrow integration, deployment, and fork-test workspace. Production contracts and their unit, fuzz, invariant, and security tests are owned by their package.

Packages

Package	Scope	Direct workspace dependencies
shared	Cross-product interfaces, oracle/decimal helpers, flash-loan foundations, and generic test support	None
spot	Paired plDXY synthetics, staking, leverage routers, yield adapters, Spot oracles, and INVAR	shared
options	Fully collateralized covered calls, margin and settlement, option tokens, and DOV vaults	shared, Spot API
perps	Delayed-order bounded perpetuals, margin clearing, a tranched LP pool, execution routing, and lenses	shared
perps-aa	ERC-4337 v0.8 verifying paymaster and deployment tooling for sponsored perps calls	None
perps-aa-client	Vendor-neutral action builders, sponsorship envelope validation, and UserOperation orchestration	None

All package imports use stable aliases:

@plether/shared/  -> packages/shared/src/
@plether/spot/    -> packages/spot/src/
@plether/options/ -> packages/options/src/
@plether/perps/   -> packages/perps/src/
@plether/perps-aa/ -> packages/perps-aa/src/

Cross-package relative imports are not allowed. Run make check-boundaries to validate the dependency rules.

Repository Layout

packages/
├── shared/       # Product-neutral production code and test support
├── spot/         # Spot production code and package-owned tests
├── options/      # Options production code and package-owned tests
├── perps/        # Perps production code and package-owned tests
├── perps-aa/     # Verifying paymaster, deployment script, and tests
└── perps-aa-client/ # Frontend account-abstraction primitives
integration/src/  # Minimal root Foundry source directory
test/             # Cross-package, deployment-script, and RPC fork tests
script/           # Deployment and operational scripts
scripts/          # Repository and CI helpers

Package source paths and fully qualified contract names begin with packages/<package>/src/. Existing deployments are unchanged by the repository layout; verification tooling and downstream source imports must use the package paths or the @plether/* remappings.

Getting Started

CI uses Foundry v1.5.1 and Solidity 0.8.35. Clone submodules before building:

git submodule update --init --recursive
make build-packages
make test
npm ci --prefix packages/perps-aa-client
npm test --prefix packages/perps-aa-client

Build

make build-packages                 # Build every Solidity package independently
make build-spot                     # Build one package through Make
forge build --root packages/perps   # Build one package directly
npm run build --prefix packages/perps-aa-client
forge build                         # Build the root integration/script workspace

Test

make test                           # Run all product packages, then root integration tests
make test-packages                  # Run every package-owned Solidity test suite
make test-options                   # Run one package
make test-integration               # Run root tests, excluding RPC-backed fork tests
forge test --root packages/perps    # Run one package directly
npm test --prefix packages/perps-aa-client

The shared package currently has no standalone test suite; its code is exercised by the product packages that consume it. See the integration test guide for package test layout, targeted test commands, fork tests, and shared fixtures.

Coverage, Formatting, and Boundaries

make coverage-spot
make coverage-options
make coverage-perps
make fmt-check
make check-boundaries

Fork Tests

RPC-backed tests cover cross-product behavior against live protocol deployments and require MAINNET_RPC_URL:

(source .env && forge test --match-path "test/fork/*" \
  --no-match-path "test/fork/PythRealUpdateFork.t.sol" \
  --fork-url "$MAINNET_RPC_URL" -vvv)

The real Pyth update test needs an additional Hermes fixture; see the integration test guide.

Continuous Integration

CI keeps package failures isolated:

• Package (shared|spot|options|perps-aa) and the dedicated perps job build each Solidity package independently.
• TypeScript (perps-aa-client) runs the client tests, typecheck, and build.
• Slither (shared|spot|options|perps|perps-aa) analyzes each package and uploads package-scoped SARIF.
• Spot, options, and perps coverage run as separate jobs with package-scoped LCOV output.
• The root build job checks formatting and dependency boundaries, builds the integration workspace, and runs root tests.
• Matrix jobs use fail-fast: false, so one package failure does not cancel results for the others.

The workflow is defined in .github/workflows/ci.yml.

Oracle maintenance

The Ethereum mainnet and Ethereum Sepolia spot deployments are retired. Their six-hour Pyth keeper workflow and standalone update scripts have been removed. See the spot package guide for deployment status.

Active Arbitrum Sepolia perps oracle maintenance runs through the plether-app oracle worker. It reads cached six-feed Pyth payloads and submits updateMarkPrice on a configurable 30-second cadence. Its operator setup is maintained in that repository. PYTH_API_KEY remains required by the perps release-preparation script.

Documentation

Start with the package that owns the product:

• Shared contracts
• Spot protocol
• Options module
• Perps protocol
• Perps accounting specification
• Perps emergency response and circuit breakers
• Perps bounded-credit white paper
• Perps bounded-credit white paper (PDF)
• Perps verifying paymaster
• Perps account-abstraction client
• Integration and fork tests

Generate NatSpec documentation for a package with:

FOUNDRY_PROFILE=docs FOUNDRY_SRC=packages/spot/src forge doc --out docs/spot
FOUNDRY_PROFILE=docs FOUNDRY_SRC=packages/options/src forge doc --out docs/options
FOUNDRY_PROFILE=docs FOUNDRY_SRC=packages/perps/src forge doc --out docs/perps

Deployment

Deployment and operational scripts live in script/. Product-specific starting points are:

• Spot operations and deployment guide
• Perps deployment guide
• Arbitrum Sepolia paymaster deployment
• Options package architecture and operational model

Always simulate the exact script and deployment scope before broadcasting.

Security

Security assumptions are product-specific:

• Spot and shared integration assumptions
• Options security model
• Perps security model and review guide
• Perps emergency response and circuit breakers
• Perps gas sponsorship security model

Some components have undergone external security review, but audit coverage is partial and release-specific. Review the security model, audit reports, deployment parameters, and exact bytecode before production use.

License

AGPL-3.0

Disclaimer

This software is provided "as is" without warranty of any kind. Use at your own risk.