Skip to content

Add SuperTokenV1Library notes and update docs #21

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
wants to merge 1 commit into from
Closed

Add SuperTokenV1Library notes and update docs #21

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
122 changes: 62 additions & 60 deletions PLAN.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,68 +1,70 @@
# Super Send SuperToken Wrapper – Plan (PR1)
# Super Send – Current Plan and Architecture

Scope and boundaries
• This repo is for a new Superfluid-based SuperToken wrapper around the already-deployed SEND v1.
• Do not include or modify the lockbox or the v1 token here—they live in a separate repo: ~/Documents/Send/send-token-upgrade.
• The wrapper is backend-only; end users never hold or interact with it. No convenience/combined functions.
Overview
- This repo orchestrates a Superfluid-based SuperToken wrapper (SENDx) around existing SEND v1 and implements a rewards path that mirrors ERC-4626 vault assets to Superfluid pool units.
- No lockbox/v1 token code lives here (send-token-upgrade repo owns those). End users never hold the wrapper; this is backend-only.

External dependencies (addresses)
• SEND v1 (underlying)
• Base mainnet (8453): 0xEab49138BA2Ea6dd776220fE26b7b8E446638956
• Base Sepolia (84532): 0xBbB542c66a7DD7BA6893C9630B30358D610FF3ee
• Local Base mainnet (845337): 0xEab49138BA2Ea6dd776220fE26b7b8E446638956
• Superfluid core
• Base mainnet:
• Resolver: 0x6a214c324553F96F04eFBDd66908685525Da0E0d
• Host: 0x4C073B3baB6d8826b8C5b229f3cfdC1eC6E47E74
• CFAv1: 0x19ba78B9cDB05A877718841c574325fdB53601bb
• SuperTokenFactory: 0xe20B9a38E0c96F61d1bA6b42a61512D56Fea1Eb3
• Base Sepolia:
• Resolver: 0x21d4E9fbB9DB742E6ef4f29d189a7C18B0b59136
• Host: 0x109412E3C84f0539b43d39dB691B08c90f58dC7c
• CFAv1: 0x6836F23d6171D74Ef62FcF776655aBcD2bcd62Ef
• SuperTokenFactory: 0x7447E94Dfe3d804a9f46Bf12838d467c912C8F6C
Architecture
- Wrapper
- Created or discovered via scripts/wrapper/create.ts using SuperTokenFactory.
- Persisted to deployments/wrapper.{chainId}.json.
- Rewards
- Contract: contracts/rewards/RewardsManager.sol
- Purpose: aggregate a user’s assets across multiple ERC-4626 vaults (same underlying, e.g., USDC) and update Superfluid pool units to match.
- Wrapper + Pool lifecycle: the constructor first resolves or creates the SENDx wrapper via SuperTokenFactory (if canonical wrapper is absent), then creates the Superfluid Pool (admin = this contract) via GDA. No external wrapper/pool addresses are needed.
- AccessControl: minimal — DEFAULT_ADMIN_ROLE is set to the provided admin; units are set purely based on on-chain vault balances (no custom operator roles).

Operational context
• Tests and deployments treat SEND v1 as an external dependency (attach by address; do not deploy it).
• Keep env vars: EOA_DEPLOYER, ETHERSCAN_API_KEY. For forked tests, impersonate as needed.
• Local dev: bun run test (Hardhat tests on Base fork); ./bin/anvil-deploy to run wrapper deploy flow locally.
Tooling and scripts
- Wrapper discovery/creation
- CREATE_WRAPPER=true bunx hardhat run scripts/wrapper/create.ts --network anvil
- Rewards deploy
- bunx hardhat run scripts/rewards/deploy.ts --network <net>
- Resolves: SEND v1 and SuperTokenFactory, SendEarnFactory, underlying asset (via vault IERC4626.asset()), deploys RewardsManager(sendV1, superTokenFactory, sendEarnFactory, asset, admin, minAssets), then reads pool() for deployments JSON.
- Holder funding helper (local/fork testing)
- SHARE_TOKEN_ADDRESS=0xVault SHARE_HOLDER=0xHolder AMOUNT_ASSETS=1000000 \
bunx hardhat run scripts/rewards/fundHolder.ts --network anvil

Defaults (can be overridden later)
• Wrapper name/symbol: “Super Send” / “SENDx”
• Underlying decimals: 18
• Upgradability: SEMI_UPGRADABLE
• Owner: EOA_DEPLOYER (script signer only; wrapper is created via SuperTokenFactory)
• Networks in scope: Base mainnet (8453), Base Sepolia (84532), local Base fork (845337)
Testing strategy
- test/rewards.manager.test.ts
- Requires a SENDx wrapper and a representative ERC-4626 vault + holder.
- Env-gated: SHARE_TOKEN_ADDRESS, SHARE_HOLDER (optional ASSET_ADDRESS).
- Deploys RewardsManager (which creates pool) and calls syncVault.
- test/wrapper.ts
- Wrapper metadata, upgrade/downgrade round-trip (gated by SEND_HOLDER), optional CFA smoke (gated by RUN_CFA_SMOKE).
- Recommendation: use the anvil network for local runs (wrapper creation on the hardhat fork can fail due to provider hardfork-history constraints).

Planned PR stack
• PR1 (this PR): PLAN.md only (no code changes)
• PR2 (cleanup): Remove/ignore all legacy migration contracts/tests (SendToken, Lockbox, old Ignition module), repoint Tilt to wrapper-only
• PR3 (config + deps): Add Superfluid per-network config and ABIs; deployments/ scaffolding; README update
• PR4 (script): Viem-based wrapper create/attach script calling SuperTokenFactory.createERC20Wrapper and persisting deployments/wrapper.{chainId}.json
• PR5 (tests): Base-fork tests — metadata + upgrade/downgrade round-trip (gated by SEND_HOLDER), optional CFA smoke (gated by RUN_CFA_SMOKE)
• PR6 (ops): Repurpose bin/anvil-deploy to wrapper-only flow and update Tiltfile
Environments
- Required: EOA_DEPLOYER, ETHERSCAN_API_KEY
- Optional (tests/scripts):
- CREATE_WRAPPER=true — allow wrapper creation
- SHARE_TOKEN_ADDRESS, SHARE_HOLDER — rewards test inputs
- ASSET_ADDRESS — override vault asset discovery
- SEND_HOLDER — wrapper upgrade/downgrade test
- RUN_CFA_SMOKE=true — optional CFA smoke test
- SEND_EARN_BROADCAST_DIR — alternate path to Foundry broadcasts for vault discovery

Acceptance criteria
• No lockbox/v1 contracts or tests remain in this repo
• Superfluid ABIs installed; network addresses configured per chain
• Wrapper create/attach script works on Base fork and persists to deployments/
• Tests pass on fork:
• Metadata test always runs
• Upgrade/downgrade test passes when SEND_HOLDER is provided; otherwise skipped with a clear message
• Optional CFA smoke test passes when RUN_CFA_SMOKE=true; otherwise skipped
• README documents backend-only wrapper flow and Graphite workflow
Current status
- RewardsManager creates and administers the pool in its constructor.
- scripts/rewards/deploy.ts deploys with constructor args (sendV1, superTokenFactory, sendEarnFactory, asset, admin, minAssets) and persists the created pool.
- README and WARP docs reflect the in-constructor pool creation and the helper script for funding a holder.
- Hardhat fork block pin removed to avoid EDR/viem hardfork-history issues for wrapper creation; anvil is recommended for wrapper work.

References (Rule 3: mirror official examples; no custom Solidity)
• SuperTokenFactory: docs and contract
• https://docs.superfluid.finance/superfluid/protocol-developers/supertokens/supertokenfactory
• https://github.com/superfluid-finance/protocol-monorepo/blob/dev/packages/ethereum-contracts/contracts/superfluid/SuperTokenFactory.sol
• ISuperToken (upgrade/downgrade/metadata)
• https://github.com/superfluid-finance/protocol-monorepo/blob/dev/packages/ethereum-contracts/contracts/interfaces/superfluid/ISuperToken.sol
• CFAv1 docs and interface
• https://docs.superfluid.finance/superfluid/developers/constant-flow-agreement-cfa
• https://github.com/superfluid-finance/protocol-monorepo/blob/dev/packages/ethereum-contracts/contracts/interfaces/agreements/IConstantFlowAgreementV1.sol
• Hardhat + Viem
• https://github.com/NomicFoundation/hardhat-viem
• Ignition external call pattern (optional)
• https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-ignition
Next steps
- Optional: add a multi-vault test using batchSyncVaults([...], who) with SHARE_TOKEN_ADDRESSES to validate aggregation over multiple vaults.
- Optional: wire CI runs on anvil for deterministic wrapper creation, plus targeted Base/Sepolia smoke runs.
- Optional: small admin helpers (distributor flows) if operationally needed later — currently out of scope.

References
- 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
- GDA / Pools
- https://github.com/superfluid-finance/protocol-monorepo/blob/dev/packages/ethereum-contracts/contracts/interfaces/agreements/gdav1/IGeneralDistributionAgreementV1.sol
- CFAv1
- https://docs.superfluid.finance/superfluid/developers/constant-flow-agreement-cfa
- Hardhat + Viem
- https://github.com/NomicFoundation/hardhat-viem
- Ignition
- https://hardhat.org/hardhat-runner/plugins/nomicfoundation-hardhat-ignition

Loading