@rev-net/core-v6 0.0.39 → 0.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rev-net/core-v6",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "license": "MIT",
   "repository": {
     "type": "git",

package/src/REVDeployer.sol

@@ -43,8 +43,15 @@ import {REVDeploy721TiersHookConfig} from "./structs/REVDeploy721TiersHookConfig
 import {REVStageConfig} from "./structs/REVStageConfig.sol";
 import {REVSuckerDeploymentConfig} from "./structs/REVSuckerDeploymentConfig.sol";
 
-/// @notice `REVDeployer` deploys, manages, and operates Revnets.
-/// @dev Revnets are unowned Juicebox projects which operate autonomously after deployment.
+/// @notice Deploys and configures Revnets — autonomous Juicebox projects with pre-programmed tokenomics that cannot
+/// be
+/// changed after launch. Each revnet progresses through stages that define issuance rate, decay schedule, cash-out tax,
+/// split allocations, and auto-issuances. The deployer translates these stage configurations into Juicebox rulesets,
+/// sets up a buyback hook for secondary market routing, deploys a tiered 721 hook, optionally configures Croptop
+/// posting, and can deploy cross-chain suckers. Once deployed, the project NFT is held by this contract — no single
+/// address can modify the revnet's rules.
+/// @dev Revnets are unowned Juicebox projects which operate autonomously after deployment. Runtime data hook logic
+/// (pay/cash-out callbacks) is handled by the separate `REVOwner` contract to stay within EIP-170 size limits.
 contract REVDeployer is ERC2771Context, IREVDeployer, IERC721Receiver {
     //*********************************************************************//
     // --------------------------- custom errors ------------------------- //

package/src/REVLoans.sol

@@ -35,18 +35,15 @@ import {IREVOwner} from "./interfaces/IREVOwner.sol";
 import {REVLoan} from "./structs/REVLoan.sol";
 import {REVLoanSource} from "./structs/REVLoanSource.sol";
 
-/// @notice A contract for borrowing from revnets.
-/// @dev Tokens used as collateral are burned, and reminted when the loan is paid off. This keeps the revnet's token
-/// structure orderly.
-/// @dev The borrowable amount is the same as the cash out amount.
-/// @dev An upfront fee is taken when a loan is created. 2.5% is charged by the underlying protocol, 2.5% is charged
-/// by the
-/// revnet issuing the loan, and a variable amount charged by the revnet that receives the fees. This variable amount is
-/// chosen by the borrower, the more paid upfront, the longer the prepaid duration. The loan can be repaid anytime
-/// within the prepaid duration without additional fees.
-/// After the prepaid duration, the loan will increasingly cost more to pay off. After 10 years, the loan collateral
-/// cannot be
-/// recouped.
+/// @notice Allows revnet token holders to borrow against their tokens instead of cashing out. The borrowable amount
+/// equals what a cash-out would return. Collateral tokens are burned on borrow and re-minted on repayment, keeping the
+/// revnet's token structure orderly. Each loan is represented as an ERC-721 NFT that can be transferred.
+/// @dev Fee structure: an upfront fee is taken at borrow time. 2.5% goes to the source revnet
+/// (MIN_PREPAID_FEE_PERCENT), 1% goes to the $REV revnet (REV_PREPAID_FEE_PERCENT), and a variable amount chosen by the
+/// borrower determines the
+/// prepaid duration — the more paid upfront, the longer the borrower can hold without additional cost. After the
+/// prepaid duration expires, the repayment cost increases linearly until the loan liquidates at 10 years
+/// (LOAN_LIQUIDATION_DURATION), at which point the collateral is permanently lost.
 /// @dev The loaned amounts include the fees taken, meaning the amount paid back is the amount borrowed plus the fees.
 contract REVLoans is ERC721, ERC2771Context, JBPermissioned, Ownable, IREVLoans {
     // A library that parses the packed ruleset metadata into a friendlier format.

package/src/REVOwner.sol

@@ -28,9 +28,13 @@ import {IREVHiddenTokens} from "./interfaces/IREVHiddenTokens.sol";
 import {IREVLoans} from "./interfaces/IREVLoans.sol";
 import {REVLoanSource} from "./structs/REVLoanSource.sol";
 
-/// @notice Handles the runtime data hook and cash out hook behavior for revnets.
-/// @dev Separated from `REVDeployer` to stay within the EIP-170 contract size limit.
-/// This contract is set as the `dataHook` in each revnet's ruleset metadata.
+/// @notice The runtime hook for all revnets — set as every revnet's `dataHook` in ruleset metadata. At pay time, it
+/// coordinates the 721 hook (NFT tier minting) with the buyback hook (secondary market swap routing) and scales weight
+/// for split deductions. At cash-out time, it aggregates cross-chain total supply and surplus (including outstanding
+/// loan debt and collateral), grants suckers 0% tax, splits a 2.5% fee from non-sucker cash outs, and routes fee
+/// proceeds to the fee revnet via `afterCashOutRecordedWith`.
+/// @dev Separated from `REVDeployer` to stay within the EIP-170 contract size limit. Also implements
+/// `IJBPeerChainAdjustedAccounts` to expose loan state to peer-chain supply/surplus snapshots.
 contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAccounts {
     // A library that adds default safety checks to ERC20 functionality.
     using SafeERC20 for IERC20;
@@ -130,13 +134,14 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
     // ------------------------- external views -------------------------- //
     //*********************************************************************//
 
-    /// @notice Determine how a cash out from a revnet should be processed.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a cash out.
-    /// @dev If a sucker is cashing out, no taxes or fees are imposed.
-    /// @dev REVOwner is intentionally not registered as a feeless address. The protocol fee (2.5%) applies on top
-    /// of the rev fee — this is by design. The fee hook spec amount sent to `afterCashOutRecordedWith` will have the
-    /// protocol fee deducted by the terminal before reaching this contract, so the rev fee is computed on the
-    /// post-protocol-fee amount.
+    /// @notice Called before a cash out is recorded. Suckers get 0% tax (bridged tokens redeem at face value). For
+    /// regular holders, aggregates cross-chain total supply and surplus (including outstanding loan debt/collateral),
+    /// splits a 2.5% fee from the cashed-out token count, computes bonding curve reclaims for both the holder's portion
+    /// and the fee portion, then delegates to the buyback hook for potential swap routing.
+    /// @dev Part of `IJBRulesetDataHook`. REVOwner is intentionally not registered as a feeless address — the
+    /// protocol
+    /// fee (2.5%) applies on top of the rev fee. The fee hook spec amount sent to `afterCashOutRecordedWith` will have
+    /// the protocol fee deducted by the terminal before reaching this contract.
     /// @param context Standard Juicebox cash out context. See `JBBeforeCashOutRecordedContext`.
     /// @return cashOutTaxRate The cash out tax rate, which influences the amount of terminal tokens which get cashed
     /// out.
@@ -289,8 +294,11 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         return (cashOutTaxRate, cashOutCount, totalSupply, effectiveSurplusValue, hookSpecifications);
     }
 
-    /// @notice Before a revnet processes an incoming payment, determine the weight and pay hooks to use.
-    /// @dev This function is part of `IJBRulesetDataHook`, and gets called before the revnet processes a payment.
+    /// @notice Called before a payment is recorded. Coordinates the 721 hook (NFT tier minting with split deductions)
+    /// with the buyback hook (which may route funds through a Uniswap pool for a better token price). Merges their hook
+    /// specifications and scales the minting weight so payers only receive tokens proportional to funds entering the
+    /// project (not the split portion).
+    /// @dev Part of `IJBRulesetDataHook`. The 721 hook spec comes first in the returned array.
     /// @param context Standard Juicebox payment context. See `JBBeforePayRecordedContext`.
     /// @return weight The weight which revnet tokens are minted relative to. This can be used to customize how many
     /// tokens get minted by a payment.
@@ -347,8 +355,11 @@ contract REVOwner is IJBRulesetDataHook, IJBCashOutHook, IJBPeerChainAdjustedAcc
         if (usesBuybackHook) hookSpecifications[usesTiered721Hook ? 1 : 0] = buybackHookSpecs[0];
     }
 
-    /// @notice A flag indicating whether an address has permission to mint a revnet's tokens on-demand.
-    /// @dev Required by the `IJBRulesetDataHook` interface.
+    /// @notice Returns whether an address may mint a revnet's tokens on-demand. Grants permission to: the loans
+    /// contract (re-mints collateral on repayment), hidden tokens contract (re-mints on reveal), buyback hook and its
+    /// delegates
+    /// (mints tokens from pool swaps), and suckers (mints bridged tokens on the destination chain).
+    /// @dev Part of `IJBRulesetDataHook`.
     /// @param revnetId The ID of the revnet to check permissions for.
     /// @param ruleset The ruleset to check the mint permission for.
     /// @param addr The address to check the mint permission of.

package/src/structs/REVAutoIssuance.sol

@@ -1,8 +1,10 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member chainId The ID of the chain on which the mint should be honored.
-/// @custom:member count The number of tokens that should be minted.
+/// @notice A per-stage token mint that happens without any payment — think of it as a scheduled premint. Each auto
+/// issuance specifies a chain, beneficiary, and token count. Can be claimed once per stage via `autoIssueFor`.
+/// @custom:member chainId The chain ID where this auto-issuance should be honored (only mints on the matching chain).
+/// @custom:member count The number of tokens to mint for the beneficiary.
 /// @custom:member beneficiary The address that will receive the minted tokens.
 struct REVAutoIssuance {
     uint32 chainId;

package/src/structs/REVConfig.sol

@@ -4,11 +4,14 @@ pragma solidity ^0.8.0;
 import {REVDescription} from "./REVDescription.sol";
 import {REVStageConfig} from "./REVStageConfig.sol";
 
-/// @custom:member description The description of the revnet.
-/// @custom:member baseCurrency The currency that the issuance is based on.
-/// @custom:member splitOperator The address that will receive the token premint and initial production split,
-/// and who is allowed to change who the operator is. Only the operator can replace itself after deployment.
-/// @custom:member stageConfigurations The periods of changing constraints.
+/// @notice Top-level configuration for deploying a revnet. Defines the revnet's identity, base currency for issuance
+/// pricing, the split operator (who receives production splits and can reassign that role), and the ordered list of
+/// stages that govern the revnet's lifecycle.
+/// @custom:member description The revnet's name, ticker, metadata URI, and deployment salt.
+/// @custom:member baseCurrency The currency that issuance pricing is denominated in (e.g. ETH or USD).
+/// @custom:member splitOperator The address that receives production splits and can reassign the operator role.
+/// Only the current operator can replace itself after deployment.
+/// @custom:member stageConfigurations The ordered stages that define how the revnet's tokenomics evolve over time.
 struct REVConfig {
     REVDescription description;
     uint32 baseCurrency;

package/src/structs/REVDescription.sol

@@ -1,11 +1,12 @@
 // SPDX-License-Identifier: MIT
 pragma solidity ^0.8.0;
 
-/// @custom:member name The name of the ERC-20 token being create for the revnet.
-/// @custom:member ticker The ticker of the ERC-20 token being created for the revnet.
-/// @custom:member uri The metadata URI containing revnet's info.
-/// @custom:member salt Revnets deployed across chains by the same address with the same salt will have the same
-/// address.
+/// @notice Identity and metadata for a revnet deployment.
+/// @custom:member name The name of the ERC-20 token created for the revnet.
+/// @custom:member ticker The ticker symbol of the ERC-20 token created for the revnet.
+/// @custom:member uri The metadata URI containing the revnet's off-chain info (logo, description, links).
+/// @custom:member salt A deployment salt — revnets deployed across chains by the same address with the same salt get
+/// deterministic matching addresses.
 struct REVDescription {
     string name;
     string ticker;

package/src/structs/REVLoan.sol

@@ -3,12 +3,15 @@ pragma solidity ^0.8.0;
 
 import {REVLoanSource} from "./REVLoanSource.sol";
 
-/// @custom:member borrowedAmount The amount that is being borrowed.
-/// @custom:member collateralTokenCount The number of collateral tokens currently accounted for.
+/// @notice An active loan against a revnet. The borrower locked collateral tokens (which were burned) and received
+/// funds from the revnet's terminal. The loan can be repaid within the prepaid duration at no extra cost; after that,
+/// repayment cost increases linearly until liquidation at 10 years.
+/// @custom:member amount The amount borrowed (includes fees taken at creation).
+/// @custom:member collateral The number of revnet tokens burned as collateral.
 /// @custom:member createdAt The timestamp when the loan was created.
-/// @custom:member prepaidFeePercent The percentage of the loan's fees that were prepaid.
-/// @custom:member prepaidDuration The duration that the loan was prepaid for.
-/// @custom:member source The source of the loan.
+/// @custom:member prepaidFeePercent The percentage of fees prepaid at creation (determines prepaid duration).
+/// @custom:member prepaidDuration The duration (seconds) during which repayment costs nothing beyond the original
+/// amount. @custom:member source The terminal and token from which funds were drawn.
 struct REVLoan {
     uint112 amount;
     uint112 collateral;

package/src/structs/REVStageConfig.sol

@@ -5,22 +5,20 @@ import {JBSplit} from "@bananapus/core-v6/src/structs/JBSplit.sol";
 
 import {REVAutoIssuance} from "./REVAutoIssuance.sol";
 
-/// @custom:member startsAtOrAfter The timestamp to start a stage at the given rate at or after.
-/// @custom:member autoIssuances The configurations of mints during this stage.
-/// @custom:member splitPercent The percentage of newly issued tokens that should be split with the operator, out
-/// of 10_000 (JBConstants.MAX_RESERVED_PERCENT).
-/// @custom:member splits The splits for the revnet.
-/// @custom:member initialIssuance The number of revnet tokens that one unit of the revnet's base currency will buy, as
-/// a fixed point number
-/// with 18 decimals.
-/// @custom:member issuanceCutFrequency The number of seconds between applied issuance decreases. This
-/// should be at least 24 hours.
-/// @custom:member issuanceCutPercent The percent that issuance should decrease over time. This percentage is out
-/// of 1_000_000_000 (JBConstants.MAX_CUT_PERCENT). 0% corresponds to no issuance increase.
-/// @custom:member cashOutTaxRate The factor determining how much each token can cash out from the revnet once
-/// cashed out. This rate is out of 10_000 (JBConstants.MAX_CASH_OUT_TAX_RATE). 0% corresponds to no tax when cashing
-/// out.
-/// @custom:member extraMetadata Extra info to attach set into this stage that may affect hooks.
+/// @notice A stage in a revnet's lifecycle. Each stage defines the token issuance rate, how quickly it decays, what
+/// percentage goes to splits, and the cash-out tax rate. Stages are processed in order — each one activates at or
+/// after
+/// its `startsAtOrAfter` timestamp.
+/// @custom:member startsAtOrAfter The earliest timestamp this stage can begin. Must be strictly increasing across
+/// stages. @custom:member autoIssuances Tokens to mint without payment during this stage (per-chain, per-beneficiary).
+/// @custom:member splitPercent The percentage of newly issued tokens routed to splits, out of 10,000.
+/// @custom:member splits The split recipients for this stage's production allocation.
+/// @custom:member initialIssuance Tokens per unit of base currency at stage start (18-decimal fixed point).
+/// @custom:member issuanceCutFrequency Seconds between each issuance reduction. Should be >= 24 hours.
+/// @custom:member issuanceCutPercent How much issuance decreases each period, out of 1,000,000,000. 0 = no decay.
+/// @custom:member cashOutTaxRate The tax on cash outs, out of 10,000. 0 = no tax (full reclaim). Higher = more tax
+/// retained by the treasury.
+/// @custom:member extraMetadata Additional metadata bits passed to hooks for stage-specific behavior.
 struct REVStageConfig {
     uint48 startsAtOrAfter;
     REVAutoIssuance[] autoIssuances;