@rev-net/core-v6 0.0.6 → 0.0.7

package/SKILLS.md

@@ -128,7 +128,7 @@ Deploy and manage Revnets -- autonomous, unowned Juicebox projects with staged i
 | Mapping | Type | Purpose |
 |---------|------|---------|
 | `isLoanSourceOf` | `revnetId => terminal => token => bool` | Is this (terminal, token) pair used for loans? |
-| `numberOfLoansFor` | `revnetId => uint256` | Counter for loan numbering |
+| `totalLoansBorrowedFor` | `revnetId => uint256` | Counter for loan numbering |
 | `totalBorrowedFrom` | `revnetId => terminal => token => uint256` | Tracks debt per loan source |
 | `totalCollateralOf` | `revnetId => uint256` | Sum of all burned collateral |
 | `_loanOf` | `loanId => REVLoan` | Per-loan state |

package/docs/book.toml

@@ -7,7 +7,7 @@ no-section-label = true
 additional-js = ["solidity.min.js"]
 additional-css = ["book.css"]
 mathjax-support = true
-git-repository-url = "https://github.com/rev-net/revnet-core-v5"
+git-repository-url = "https://github.com/rev-net/revnet-core-v6"
 
 [output.html.fold]
 enable = true

package/docs/src/README.md

@@ -1,88 +1,185 @@
-# Revnet
+# Revnet Core
 
-This repo provides tools for deploying Revnets: Retailistic networks, using the Juicebox and Uniswap protocols for its implementation.
+Deploy and operate Revnets: unowned Juicebox projects that run autonomously according to predefined stages, with built-in token-collateralized loans.
 
-For a Retailism TLDR, see https://jango.eth.sucks/9E01E72C-6028-48B7-AD04-F25393307132/.
+[Docs](https://docs.juicebox.money) | [Discord](https://discord.gg/nT3XqbzNEr)
 
-For more Retailism information, see:
+## What is a Revnet?
 
-A Retailistic View on CAC and LTV
-https://jango.eth.limo/572BD957-0331-4977-8B2D-35F84D693276/
+A Revnet is a treasury-backed token that runs itself. No owners, no governors, no multisigs. Once deployed, a revnet follows its predefined stages forever, backed by the Juicebox and Uniswap protocols.
 
-Modeling Retailism
-https://jango.eth.limo/B762F3CC-AEFE-4DE0-B08C-7C16400AF718/
+## Conceptual Overview
 
-Retailism for Devs, Investors, and Customers 
-https://jango.eth.limo/3EB05292-0376-4B7D-AFCF-042B70673C3D/
+Revnets are autonomous Juicebox projects with predetermined economic stages. Each stage defines issuance rates, decay schedules, cash-out taxes, reserved splits, and auto-issuance allocations. Once deployed, these parameters cannot be changed -- the revnet operates on its own forever.
 
-Observations: Network dynamics similar between atoms, cells, organisms, groups, dance parties.
-https://jango.eth.limo/CF40F5D2-7BFE-43A3-9C15-1C6547FBD15C/
+### Stage-Based Lifecycle
 
-Join the conversation here: https://discord.gg/nT3XqbzNEr
+```
+1. Deploy revnet with stage configurations
+   → REVDeployer.deployFor(revnetId=0, config, terminals, ...)
+   → Creates Juicebox project owned by REVDeployer (permanently)
+   → Deploys ERC-20 token, configures buyback pools, deploys suckers
+   |
+2. Stage 1 begins (startsAtOrAfter or block.timestamp)
+   → Tokens issued at initialIssuance rate per unit of base currency
+   → Issuance decays by issuanceCutPercent every issuanceCutFrequency
+   → splitPercent of new tokens go to reserved splits
+   → Cash outs taxed at cashOutTaxRate (2.5% fee to fee revnet)
+   |
+3. Stage transitions happen automatically
+   → When startsAtOrAfter timestamp is reached for next stage
+   → New issuance rate, tax rate, splits, etc. take effect
+   → No governance, no votes, no owner action required
+   |
+4. Participants can borrow against their tokens
+   → REVLoans.borrowFrom(revnetId, source, collateral, ...)
+   → Collateral tokens are burned, funds pulled from treasury
+   → Loan is an ERC-721 NFT, liquidates after 10 years
+   |
+5. Ongoing operations (permissionless or split operator)
+   → Auto-issuance claims (permissionless)
+   → Buyback pool configuration (split operator)
+   → Sucker deployment (split operator, if ruleset allows)
+   → Split group updates (split operator)
+```
 
-In this repo, you'll find:
-- a basic revnet design implemented in `BasicRevnetDeployer`.
-- a design that accepts other pay hooks implemented in `PayHookRevnetDeployer`, which accepts other pay hooks that'll get used throughout the revnet's lifetime as it receives payments.
-- a design that supports tiered 721 pay hooks implemented in `Tiered721RevnetDeployer`, which accepts data to deploy a tiered 721 pay hook that'll get used throughout the network's lifetime as people pay in, alongside other pay hooks that may also be specified.
-- a design supports croptop, implemented in `CroptopRevnetDeployer`, which accepts data to deploy a tiered 721 pay hook that'll get used throughout the project's lifetime as people pay in that can also be posted to by the public through the croptop publisher contract. See https://croptop.eth.limo for more context.
+### Token-Collateralized Loans
 
-You can use these contracts to deploy treasuries from etherscan, or wherever else they've been exposed from.
+`REVLoans` lets participants borrow against their revnet tokens. Unlike traditional lending:
 
-## Install
+- **Collateral is burned, not held.** Tokens are destroyed on borrow and re-minted on repay. This keeps the token supply accurate -- collateral tokens don't exist during the loan.
+- **Borrowable amount = cash-out value.** The bonding curve determines how much you can borrow for a given amount of collateral.
+- **Prepaid fee model.** Borrowers choose a prepaid fee (2.5%-50%) that buys an interest-free window. After that window, a time-proportional source fee accrues.
+- **Each loan is an ERC-721 NFT.** Loans can be transferred, and expired loans (10 years) can be liquidated by anyone.
+
+### Deployer Variants
+
+- **Basic revnet** -- `deployFor` with stage configurations mapped to Juicebox rulesets.
+- **Tiered 721 revnet** -- `deployWith721sFor` adds a tiered 721 pay hook that mints NFTs as people pay.
+- **Croptop revnet** -- A tiered 721 revnet with Croptop posting criteria, allowing the public to post content.
+
+## Architecture
 
-For `npm` projects (recommended):
+| Contract | Description |
+|----------|-------------|
+| `REVDeployer` | Deploys revnets as Juicebox projects owned by the deployer contract itself (no human owner). Translates stage configurations into Juicebox rulesets, manages buyback hooks, tiered 721 hooks, suckers, split operators, auto-issuance, and cash-out fees. Acts as the ruleset data hook and cash-out hook for every revnet it deploys. |
+| `REVLoans` | Lets participants borrow against their revnet tokens. Collateral tokens are burned on borrow and re-minted on repayment. Each loan is an ERC-721 NFT. Charges a prepaid fee (2.5% min, 50% max) that determines the interest-free duration; after that window, a time-proportional source fee accrues. Loans liquidate after 10 years. |
+
+### How They Relate
+
+`REVDeployer` owns every revnet's Juicebox project NFT and holds all administrative permissions. During deployment it grants `REVLoans` the `USE_ALLOWANCE` permission so loans can pull funds from the revnet's terminal. `REVLoans` verifies that a revnet was deployed by its expected `REVDeployer` before issuing any loan.
+
+### Interfaces
+
+| Interface | Description |
+|-----------|-------------|
+| `IREVDeployer` | Deployment, data hooks, auto-issuance, split operator management, sucker deployment, plus events. |
+| `IREVLoans` | Borrow, repay, refinance, liquidate, views, plus events. |
+
+## Install
 
 ```bash
-npm install @bananapus/721-hook
+npm install @rev-net/core-v6
 ```
 
-For `forge` projects (not recommended):
+If using Forge directly:
 
 ```bash
-forge install Bananapus/nana-721-hook
+npm install && forge install
 ```
 
-Add `@bananapus/721-hook/=lib/nana-721-hook/` to `remappings.txt`. You'll also need to install `nana-721-hook`'s dependencies and add similar remappings for them.
+If `forge install` has issues, try `git submodule update --init --recursive`.
 
 ## Develop
 
-`nana-721-hook` uses [npm](https://www.npmjs.com/) for package management and the [Foundry](https://github.com/foundry-rs/foundry) development toolchain for builds, tests, and deployments. To get set up, [install Node.js](https://nodejs.org/en/download) and install [Foundry](https://github.com/foundry-rs/foundry):
+| Command | Description |
+|---------|-------------|
+| `forge build` | Compile contracts |
+| `forge test` | Run tests (20+ test files covering deployment, lifecycle, loans, attacks, invariants) |
+| `forge test -vvvv` | Run tests with full traces |
 
-```bash
-curl -L https://foundry.paradigm.xyz | sh
+## Repository Layout
+
+```
+src/
+  REVDeployer.sol                                # Revnet deployer + data hook (~1,256 lines)
+  REVLoans.sol                                   # Token-collateralized lending (~1,333 lines)
+  interfaces/
+    IREVDeployer.sol                             # Deployer interface + events
+    IREVLoans.sol                                # Loans interface + events
+  structs/
+    REVConfig.sol                                # Top-level deployment config
+    REVDescription.sol                           # ERC-20 metadata (name, ticker, uri, salt)
+    REVStageConfig.sol                           # Economic stage parameters
+    REVAutoIssuance.sol                          # Per-stage cross-chain premint
+    REVLoan.sol                                  # Loan state
+    REVLoanSource.sol                            # Terminal + token pair for loans
+    REVDeploy721TiersHookConfig.sol              # 721 hook deployment config
+    REVCroptopAllowedPost.sol                    # Croptop posting criteria
+    REVSuckerDeploymentConfig.sol                # Cross-chain sucker deployment
+test/
+  REV.integrations.t.sol                         # Deployment, payments, cash-outs
+  REVLifecycle.t.sol                             # Stage transitions, weight decay
+  REVAutoIssuanceFuzz.t.sol                      # Auto-issuance fuzz tests
+  REVInvincibility.t.sol                         # Economic property fuzzing
+  REVInvincibilityHandler.sol                    # Fuzz handler
+  REVDeployerAuditRegressions.t.sol              # Deployer audit regressions
+  REVLoansSourced.t.sol                          # Multi-source loan tests
+  REVLoansUnSourced.t.sol                        # Loan error cases
+  REVLoansFeeRecovery.t.sol                      # Fee calculation tests
+  REVLoansAttacks.t.sol                          # Flash loan, reentrancy scenarios
+  REVLoans.invariants.t.sol                      # Loan fuzzing invariants
+  REVLoansAuditRegressions.t.sol                 # Loan audit regressions
+  TestPR09-32_*.t.sol                            # Per-PR regression tests
+  helpers/
+    MaliciousContracts.sol                       # Attack contract mocks
+  mock/
+    MockBuybackDataHook.sol                      # Mock for buyback hook tests
+script/
+  Deploy.s.sol                                   # Sphinx multi-chain deployment
+  helpers/
+    RevnetCoreDeploymentLib.sol                  # Deployment artifact reader
 ```
 
-You can download and install dependencies with:
+## Permissions
 
-```bash
-npm install && forge install
-```
+### Split Operator (per-revnet)
+
+The split operator has these default permissions:
+
+| Permission | Purpose |
+|------------|---------|
+| `SET_SPLIT_GROUPS` | Change reserved token splits |
+| `SET_BUYBACK_POOL` | Configure Uniswap buyback pool |
+| `SET_BUYBACK_TWAP` | Adjust TWAP window for buyback |
+| `SET_PROJECT_URI` | Update project metadata |
+| `ADD_PRICE_FEED` | Add price oracle |
+| `SUCKER_SAFETY` | Emergency sucker functions |
+| `SET_BUYBACK_HOOK` | Swap buyback hook |
+| `SET_ROUTER_TERMINAL` | Swap terminal |
 
-If you run into trouble with `forge install`, try using `git submodule update --init --recursive` to ensure that nested submodules have been properly initialized.
+Plus optional from 721 hook config: `ADJUST_721_TIERS`, `SET_721_METADATA`, `MINT_721`, `SET_721_DISCOUNT_PERCENT`.
 
-Some useful commands:
+### Global Permissions
 
-| Command               | Description                                         |
-| --------------------- | --------------------------------------------------- |
-| `forge build`         | Compile the contracts and write artifacts to `out`. |
-| `forge fmt`           | Lint.                                               |
-| `forge test`          | Run the tests.                                      |
-| `forge build --sizes` | Get contract sizes.                                 |
-| `forge coverage`      | Generate a test coverage report.                    |
-| `foundryup`           | Update foundry. Run this periodically.              |
-| `forge clean`         | Remove the build artifacts and cache directories.   |
+| Grantee | Permission | Scope |
+|---------|------------|-------|
+| `SUCKER_REGISTRY` | `MAP_SUCKER_TOKEN` | All revnets (wildcard projectId=0) |
+| `REVLoans` | `USE_ALLOWANCE` | All revnets (wildcard projectId=0) |
 
-To learn more, visit the [Foundry Book](https://book.getfoundry.sh/) docs.
+### Permissionless Operations
 
-## Scripts
+- `autoIssueFor` -- claim auto-issuance tokens (anyone)
+- `burnHeldTokensOf` -- burn reserved tokens held by deployer (anyone)
 
-For convenience, several utility commands are available in `package.json`.
+## Risks
 
-| Command                           | Description                            |
-| --------------------------------- | -------------------------------------- |
-| `npm test`                        | Run local tests.                       |
-| `npm run coverage:lcov`           | Generate an LCOV test coverage report. |
-| `npm run deploy:ethereum-mainnet` | Deploy to Ethereum mainnet             |
-| `npm run deploy:ethereum-sepolia` | Deploy to Ethereum Sepolia testnet     |
-| `npm run deploy:optimism-mainnet` | Deploy to Optimism mainnet             |
-| `npm run deploy:optimism-testnet` | Deploy to Optimism testnet             |
+- **No human owner.** `REVDeployer` permanently holds the project NFT. There is no function to release it. This is by design -- revnets are ownerless. But it means bugs in stage configurations cannot be fixed after deployment.
+- **Loan flash-loan exposure.** `borrowableAmountFrom` reads live surplus, which can be inflated via flash loans. A borrower could temporarily inflate the treasury to borrow more than the sustained value would support.
+- **uint112 truncation.** `REVLoan.amount` and `REVLoan.collateral` are `uint112` -- values above ~5.19e33 truncate silently.
+- **Cash-out fee stacking.** Cash outs incur both the Juicebox terminal fee (2.5%) and the revnet cash-out fee (2.5% to fee revnet). These compound.
+- **Auto-issuance stage ID mismatch.** Stage IDs are computed as `block.timestamp + i` during deployment, but actual Juicebox ruleset IDs depend on queuing logic. If timestamps don't align, auto-issuance for later stages may be unclaimed.
+- **NATIVE_TOKEN on non-ETH chains.** Using `JBConstants.NATIVE_TOKEN` on Celo or Polygon means CELO/MATIC, not ETH. Use ERC-20 WETH instead. The matching hash does NOT catch this -- it covers economic parameters but NOT terminal configurations.
+- **30-day cash-out delay.** When deploying an existing revnet to a new chain where the first stage has already started, a 30-day delay is imposed before cash outs are allowed, preventing cross-chain liquidity arbitrage.
+- **Loan source array growth.** `_loanSourcesOf[revnetId]` is unbounded. If an attacker creates loans from many different terminals/tokens, the array grows without limit.
+- **10-year loan liquidation.** Expired loans (10+ years) can be liquidated by anyone. The burned collateral is permanently lost -- it was destroyed at borrow time.

package/docs/src/SUMMARY.md

@@ -6,8 +6,6 @@
     - [IREVLoans](src/interfaces/IREVLoans.sol/interface.IREVLoans.md)
   - [❱ structs](src/structs/README.md)
     - [REVAutoIssuance](src/structs/REVAutoIssuance.sol/struct.REVAutoIssuance.md)
-    - [REVBuybackHookConfig](src/structs/REVBuybackHookConfig.sol/struct.REVBuybackHookConfig.md)
-    - [REVBuybackPoolConfig](src/structs/REVBuybackPoolConfig.sol/struct.REVBuybackPoolConfig.md)
     - [REVConfig](src/structs/REVConfig.sol/struct.REVConfig.md)
     - [REVCroptopAllowedPost](src/structs/REVCroptopAllowedPost.sol/struct.REVCroptopAllowedPost.md)
     - [REVDeploy721TiersHookConfig](src/structs/REVDeploy721TiersHookConfig.sol/struct.REVDeploy721TiersHookConfig.md)