Skip to content

Update docs: manager requires existing SuperToken #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
youngkidwarrior wants to merge 1 commit into from
Closed

Update docs: manager requires existing SuperToken #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,12 @@ Scripts and flows
```sh
bun run test
```
- Multi-vault aggregation (optional): set VAULT_ADDRESSES as a comma-separated list and (optionally) VAULT_HOLDERS as a comma-separated list (defaults to SHARE_HOLDER for all). (SHARE_TOKEN_ADDRESSES is accepted for backward compatibility.)
```sh
SHARE_TOKEN_ADDRESSES=0xVault1,0xVault2 \
VAULT_HOLDERS=0xHolder1,0xHolder2 \
bunx hardhat test --network anvil
```
- Local wrapper discovery/creation (PR4):
- Discover existing wrapper or create if not present (set CREATE_WRAPPER=true):
```sh
Expand All @@ -29,10 +35,29 @@ Scripts and flows
```sh
bunx hardhat run scripts/wrapper/create.ts --network base
```
- Deploy RewardsManager with Hardhat Ignition (consolidated manager):
- Prepare parameters by filling ignition/parameters/RewardsManager.sample.json and saving as, for example, ignition/parameters/RewardsManager.base.json
- Values required: sendx (pre-existing SuperToken wrapper), sendEarnFactory, asset (USDC), admin (DEFAULT_ADMIN_ROLE holder), minAssets. The contract creates the Superfluid pool in its constructor; it no longer creates the SuperToken wrapper.
- Deploy:
```sh
bunx hardhat ignition deploy ./ignition/modules/RewardsManager.ts \
--network base \
--parameters ignition/parameters/RewardsManager.base.json
```
- Example module structure mirrors: /Users/vict0xr/Documents/Send/send-token-upgrade/ignition/modules/SendToken.ts
- See Ignition docs for parameters JSON: https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-ignition
- Local deploy orchestration (anvil state helper):
```sh
./bin/anvil-deploy
```
- Fund a holder with vault shares locally (to exercise syncVault in tests):
```sh
VAULT_ADDRESS=0xVault \
SHARE_HOLDER=0xHolder \
AMOUNT_ASSETS=1000000 \
bunx hardhat run scripts/rewards/fundHolder.ts --network anvil
```
(SHARE_TOKEN_ADDRESS is accepted for backward compatibility.)
- Wrapper address persistence
- deployments/wrapper.{chainId}.json

Expand All @@ -46,3 +71,4 @@ References (Rule 3: mirror official examples; no custom Solidity)
- ISuperToken: https://github.com/superfluid-finance/protocol-monorepo/blob/dev/packages/ethereum-contracts/contracts/interfaces/superfluid/ISuperToken.sol
- CFAv1: https://docs.superfluid.finance/superfluid/developers/constant-flow-agreement-cfa
- Hardhat + Viem: https://github.com/NomicFoundation/hardhat-viem
- Hardhat Ignition: https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-ignition
82 changes: 82 additions & 0 deletions WARP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

1) Overview
- This repo orchestrates a Superfluid SuperToken wrapper (SENDx) around the existing SEND v1 token, for backend-only flows. No custom wrapper Solidity exists here; wrapper creation uses Superfluid’s official contracts/ABIs and viem via Hardhat.
- SEND v1 and Superfluid core addresses for Base mainnet and Base Sepolia are defined in config/superfluid.ts and README.md.

2) Tooling and environment
- Prereqs: Bun + Node, Hardhat, Anvil (local Base fork), Foundry’s cast (used by bin/anvil-deploy), and .env support (direnv optional via .envrc).
- Required env vars: EOA_DEPLOYER, ETHERSCAN_API_KEY. Optional env flags used by scripts/tests: CREATE_WRAPPER, SEND_HOLDER, RUN_CFA_SMOKE, SHARE_TOKEN_ADDRESS, SEND_EARN_BROADCAST_DIR, ANVIL_BLOCK_TIME.
- Networks (see hardhat.config.ts): hardhat (forking Base mainnet at a fixed block), anvil (http://127.0.0.1:8546, chainId 845337), base (8453), sepolia (84532). Etherscan settings are included for base and sepolia.

3) Common commands (supported by this repo)
- Install dependencies
- bun install
- npm ci also works (package-lock.json present), but examples assume Bun.
- Compile
- bunx hardhat compile
- Run all tests
- bun run test (package.json maps to "hardhat test")
- Equivalent: bunx hardhat test
- Run a single test file
- bunx hardhat test test/wrapper.ts
- bunx hardhat test test/rewards.manager.test.ts
- Optional multi-vault aggregation test
- VAULT_ADDRESSES=0xVault1,0xVault2 [VAULT_HOLDERS=0xHolder1,0xHolder2] bunx hardhat test --network anvil
(SHARE_TOKEN_ADDRESSES is accepted for backward compatibility.)
- Filter tests by name (Mocha grep)
- bunx hardhat test --grep "upgrade and downgrade"
- Create or discover SENDx wrapper on a network
- Local anvil (requires Anvil at 127.0.0.1:8546):
- CREATE_WRAPPER=true bunx hardhat run scripts/wrapper/create.ts --network anvil
- Base mainnet:
- bunx hardhat run scripts/wrapper/create.ts --network base
- Base Sepolia:
- bunx hardhat run scripts/wrapper/create.ts --network sepolia
- Local deploy orchestration helper
- ./bin/anvil-deploy
Notes: Expects Anvil at http://127.0.0.1:8546. Funds EOA_DEPLOYER on the fork, sets CREATE_WRAPPER=true, runs wrapper creation, and toggles mining settings (uses Foundry cast + Bun + Hardhat).
- Deploy RewardsManager (after compile). The contract requires an existing SuperToken (SENDx) and creates the Superfluid Pool in its constructor:
- bunx hardhat run scripts/rewards/deploy.ts --network anvil
- bunx hardhat run scripts/rewards/deploy.ts --network base
- bunx hardhat run scripts/rewards/deploy.ts --network sepolia

4) Big-picture architecture
- Network/config layer
- config/superfluid.ts centralizes per-network config: SEND v1, Superfluid core (resolver, host, CFAv1), SuperTokenFactory, and wrapper metadata (name/symbol/decimals). Consumed by scripts and tests.
- Wrapper flow (scripts/wrapper/create.ts)
- Resolution order: (1) deployments/wrapper.{chainId}.json if present and valid, (2) SuperTokenFactory.getCanonicalERC20Wrapper(sendV1), (3) if CREATE_WRAPPER=true, create via SuperTokenFactory.createERC20Wrapper (viem simulate->write).
- Validates a candidate wrapper by checking bytecode presence and verifying ISuperToken.getUnderlyingToken() equals configured sendV1.
- Persists deployments/wrapper.{chainId}.json with underlying, createdAt, factory, chainId.
- Local orchestration (bin/anvil-deploy)
- Uses Foundry cast RPC calls to set automine, optionally funds EOA_DEPLOYER, sets CREATE_WRAPPER=true, runs wrapper creation on --network anvil, then switches to interval mining (ANVIL_BLOCK_TIME).
- Tests
- test/wrapper.ts resolves wrapper via deployments cache or canonical mapping; can create on-demand when CREATE_WRAPPER=true. It validates metadata/underlying; upgrade/downgrade round-trip is gated by SEND_HOLDER; CFA smoke checks gated by RUN_CFA_SMOKE ensure host/CFA calls are reachable without committing to flow lifecycle state.
- test/rewards.manager.test.ts resolves SENDx and a representative ERC-4626 vault (or ASSET_ADDRESS), deploys RewardsManager (which creates the pool), and calls syncVault(holder) when SHARE_TOKEN_ADDRESS and SHARE_HOLDER are provided. Use scripts/rewards/fundHolder.ts on local forks to ensure the holder has non-zero shares.
- Rewards path
- Contract: contracts/rewards/RewardsManager.sol (minimal AccessControl) sums a user’s assets across multiple ERC-4626 vaults sharing the same underlying (e.g., USDC) and mirrors that total to Superfluid Pool units via updateMemberUnits. It creates the Superfluid pool in its constructor using SuperTokenV1Library with itself as admin.
- Deployment: scripts/rewards/deploy.ts resolves SendEarnFactory and a representative share token (or uses env), derives the underlying asset via IERC4626.asset(), deploys RewardsManager (which creates the pool), then queries and persists the pool address into deployments/rewards.{chainId}.json.
- Cross-repo coupling
- For share token discovery, scripts/rewards/deploy.ts currently points to a broadcast file produced by the sibling repo send-earn-contracts. Prefer setting SHARE_TOKEN_ADDRESS or overriding the directory via SEND_EARN_BROADCAST_DIR (supported by the test) to avoid machine-specific absolute paths.
- Persistence and idempotency
- deployments/*.json caches wrapper and rewards addresses for reuse and to short-circuit subsequent runs.

5) Intentionally absent
- Lint/format: No ESLint/Prettier config or lint scripts are present; no lint commands are included here.
- Build: There is no separate build step beyond Hardhat compile; TypeScript runs via Hardhat/ts-node under Bun. No package build script exists.

6) CI guidance (optional)
- Prefer running the suite on an anvil fork for wrapper/pool creation determinism:
- Start anvil in CI (Foundry): anvil --fork-url $BASE_RPC --port 8546 --chain-id 845337
- Export envs for any gated tests (e.g., SHARE_TOKEN_ADDRESS, SHARE_HOLDER).
- Run: bunx hardhat test --network anvil
- Gate network-dependent tests via envs so CI can run a minimal subset without secrets (e.g., run wrapper metadata only).

7) References used by this repo (authoritative)
- SuperTokenFactory: https://docs.superfluid.finance/superfluid/protocol-developers/supertokens/supertokenfactory
- ISuperToken: https://github.com/superfluid-finance/protocol-monorepo/blob/dev/packages/ethereum-contracts/contracts/interfaces/superfluid/ISuperToken.sol
- CFAv1: https://docs.superfluid.finance/superfluid/developers/constant-flow-agreement-cfa
- Hardhat + viem: https://github.com/NomicFoundation/hardhat-viem