Build with revnets

A revnet is a Juicebox V6 project whose owner contract, REVOwner, enforces the stage schedule committed at launch. The operator cannot rewrite that schedule, but can have powers over split recipients, routing, metadata, bridges, and shops. Read both the launch terms and the current integration state.

This guide is written for three kinds of builder, and each section is tagged with who it is for. Project builders launch and run a revnet from this site without writing code. App builders connect a product to one with the SDK and the indexer. Contract builders extend one with Solidity. The parts overlap, so read the tags and skip what is not yours.

How a revnet worksLaunch without writing codeConnect an app with the SDKBuild a contract integrationJuicebox build guide

Amounts are bigint in the token's own decimals until the display boundary. A revnet's identity is chain ID plus project ID; a sucker group links the chains but never makes their addresses, balances, or stage IDs interchangeable.

• Addresses: deploy-all-v6 publishes one artifact per contract per chain (address, ABI, source name) under deployments/<chain>/. Everything else derives from it: the SDK's jbContractAddress map and the skills library's chain-config.json.
• Chains: Ethereum, Optimism, Base, Arbitrum, plus Sepolia and the three L2 Sepolias. The SDK's SUPPORTED_CHAINS and JB_CHAINS carry the list.
• Source: the -v6 repos are current; older Juicebox versions are not interchangeable with them.

deploy-all-v6 (addresses)revnet-core-v6nana-core-v6Every V6 repo

In Terms, each stage has an issuance rate (tokens per unit of base currency; a later stage can pick up where the previous one left off), an optional automatic cut (a percentage every N days, defaults 10% every 30 days), a cash out tax (a 0–80% slider in steps of 5, default 20%; the contracts allow anything below 100%), a split share with recipients (percent of every issuance, optionally different recipients per chain), and auto issuance rows (an amount, a beneficiary, and the chain where it can be claimed). By default the first start is set with a ten-minute buffer when the configuration is prepared; it is not ten minutes after eventual execution. You can set a later time. Subsequent stages start after the configured number of cuts or days.

Open the wizardHow the form becomes a deployFor call

A .jb file is JSON: the form's fields in the units you see on screen (days, percentages from 0 to 100, human token amounts). Import it at the top of the create page and every section fills in. Any live revnet's Extras tab exports one reconstructed from the chain, which is also the easiest way to diff what you launched against what you meant to.

An agent has two ways to launch. It can produce a .jb for you to import, check, and sign, which keeps the keys with you. Or it can call REVDeployer.deployFor itself through the SDK's buildDeployRevnetTx, which is the path for automated or scripted launches.

• Limits: up to 32 stages, 16 chains, 64 store items, 2 MB. Media cannot travel inside JSON; item images arrive as already-pinned ipfs:// URIs.
• Skills: jb-deploy-ui for launch interfaces, revnet-economics and revnet-modeler for exploring configurations. Check generated drafts against the current schema and live deployment contracts.

Draft formatEvery fieldLaunch interface skill

• Creation fee: read JBProjects.creationFee() on each chain immediately before preparing the deployment. The fee recipient and its route determine any fee-project tokens received; show the quoted fee separately from gas and relay costs.
• Token: an ERC-20 named after your revnet with your ticker. Matching deployments can share a token address across chains when the deployer, sender, configuration hash, and salts match; verify the resulting address on each chain.
• Pool: a Uniswap V4 pool per accepted token is initialized at the issuance price with a 1% fee tier, 200 tick spacing, and a two-day TWAP window. It starts empty; liquidity is added later.
• Chains: with two or more chains, Relayr submits a paid bundle. Completion depends on each chain and the relay service; do not promise a fixed settlement time. With one chain, use a wallet transaction or Safe proposal and wait for execution.
• Afterwards: each chain has its own project ID; the page lives at /<chain>:<id>. The Terms tab shows the schedule as the contracts hold it.

Liquidity lives under Owners → Market. Anyone can add liquidity to the pool through Uniswap V4's position manager, single-sided if you like; the site shows the pool's composition, depth by price band, and every position.

Cannot: change issuance, cuts, cash out taxes, split percentages, stage timing, or withdraw the balance. There is no owner key. The project NFT is held by REVOwner, which will never transfer it.

Operator tab sourceREVOwner.sol

Your team is paid in tokens: the split share of every issuance, plus any auto issuance the stage names. Recipients collect auto issuance from the Owners tab. Holders get a You card with cash out, borrow, move between chains, and claim credits. Card and bank payments go through the embedded wallet's on-ramp, which buys the accepted token first.

• Issuance and cuts: simulate both low and high revenue as issuance falls. Show tokens reaching the payer after the split, and consider every stage transition. A shorter cadence makes timing more important; the contract documentation recommends at least a day.
• Cash out tax: compare exits at several shares of total supply. A higher tax retains more of a proportional withdrawal. Loans also use the current cash out tax, so borrowing is not a shortcut around it; compare net proceeds and repayment obligations.
• Split share: stepping down across stages (30% → 20% → 10%) pays early contributors more without a governance vote later.
• Stages: align starts with actual product needs and model late payments around transitions. The final stage continues, including any recurring issuance cuts. Zero issuance prevents further minting from payments, but does not cancel other token allocations.
• Concentration: test large-holder exits, auto issuance claims, heavy borrowing, and empty local balances. Outstanding loans affect both effective supply and backing; arbitrary concentration thresholds do not establish safety.

revnet-economics skillrevnet-modeler skillrev-sim (simulator)

The root entry exports every ABI, jbContractAddress, the chain list, the bendystraw helpers, and project-metadata reads. The /v6 entry exports the reads and builders. Builders are pure: validated input in, a { chainId, address, abi, functionName, args, value } request out. Keep reads on a public client for the target chain and writes on a wallet client connected to that same chain.

Start with a TypeScript app and a viem public client for the selected chain; add a wallet client only for signing. Install @bananapus/nana-sdk-core and viem, and pin versions in your lockfile. The examples are focused integration fragments: provide the named clients, chain ID, addresses, user inputs, and error handling in your app.

import {
  buildBorrowTx, buildBridgeClaimTx, buildBridgePrepareTx, buildCashOutTx,
  buildClaimTokensTx, buildDeployRevnetTx, buildPayTx, buildRepayLoanTx,
  buildRevnetStageConfig, buildToRemoteTx, getBorrowableAmount,
  prepareHookAwareCashOut, previewPay, REV_METADATA_ALLOW_SUCKER_DEPLOYMENT,
  slippageFloor,
} from "@bananapus/nana-sdk-core/v6";

import {
  getJBContractAddress, JBCoreContracts, RevnetCoreContracts,
  jbMultiTerminalAbi, revLoansAbi, type JBChainId,
} from "@bananapus/nana-sdk-core";

const terminal = getJBContractAddress(JBCoreContracts.JBMultiTerminal, 6, chainId);
const loans = getJBContractAddress(RevnetCoreContracts.REVLoans, 6, chainId);

A Ponder service watches supported contracts and serves indexed results over GraphQL, an API where you request named fields. The index can lag, return incomplete history, or be unavailable. Distinguish loading, unavailable, stale, and empty results; a missing row is not proof that a revnet or transaction does not exist.

This site never sends GraphQL text from the browser. Each query is registered on the server under an operation id; the browser posts { operation, variables } to a same-origin route that validates the variables and forwards it. Heavier history and ranking queries are server-only. Copy that shape if you expose the index to untrusted clients.

• Key by chain: chainId + projectId, never projectId alone — the same number exists on every chain. Filter V6 rows with version: 6.
• Float, not Int: numeric arguments on singular queries are Float! (Ponder's choice); an Int! variable fails validation with no data.
• Page to the end: lists take limit and offset and return totalCount; loop rather than trusting one page.
• suckerGroupId is as-of-event: rows written before chains were linked keep the old group id; query every project in the group for full history.
• Pool reserves without RPC: sum the indexed positions at the latest swap's sqrtPriceX96 — the recipe is in the jb-bendystraw skill and this site's price chart.

import { requestBendystraw, selectBendystrawEndpoint } from "@bananapus/nana-sdk-core";

const endpoint = selectBendystrawEndpoint(
  { mainnet: "https://bendystraw.up.railway.app/graphql", testnet: "https://testnet.bendystraw.xyz/graphql" },
  { chainId },
);

type RevnetResult = {
  project: { name: string | null; balance: string; owner: string; suckerGroupId: string | null } | null;
};
type RevnetVariables = { chainId: number; projectId: number };
if (projectId > BigInt(Number.MAX_SAFE_INTEGER)) throw new Error("Project ID exceeds the indexer numeric range");

const { project } = await requestBendystraw<RevnetResult, RevnetVariables>(
  endpoint,
  `query Revnet($chainId: Float!, $projectId: Float!) {
     project(chainId: $chainId, projectId: $projectId, version: 6) {
       name balance owner suckerGroupId
     }
   }`,
  { chainId, projectId: Number(projectId) },
);
// Treat project === null as not indexed; do not turn its balances into zero.
// Generate response types from the current endpoint schema in production.

A terminal payment issues new tokens or, if the buyback hook finds a better price, buys from the pool. A direct pool swap is a different transaction that skips the split share. Compare executable, slippage-protected minimums rather than chart prices.

ERC-20 payments approve only the request's spender for only the required amount (this site uses a plain approve for pay and repay; Permit2 is reserved for direct pool swaps). Native payments carry the amount in value. Shop purchases are payments with tier metadata; show every NFT plus the token result in the confirmation.

const quote = await previewPay(publicClient, {
  chainId, terminal, projectId, token, amount, beneficiary, metadata,
});
if (quote.beneficiaryTokenCount <= 0n) throw new Error("No token output; review the payment terms");

const tx = buildPayTx({
  chainId, terminal, projectId, token, amount, beneficiary, metadata,
  minReturnedTokens: slippageFloor(quote.beneficiaryTokenCount, 100n), // 1% tolerance; 100 basis points
  memo,
});

// ERC-20: approve tx.address. Native: tx.value === amount.

previewCashOutFrom runs the real data hook and buyback decision. The route decides where the minimum goes: minTokensReclaimed on the treasury path, buyback metadata on the pool path. Re-quote after any stage, supply, balance, pool, or fee change.

Credits and claimed ERC-20 tokens behave differently on the open market. Only compare a direct swap for the claimed balance the router can actually spend.

const prepared = await prepareHookAwareCashOut(publicClient, {
  chainId, terminal, holder, projectId, cashOutCount, tokenToReclaim,
  beneficiary,
});

const { route, transaction: tx } = prepared;
// Pool routes are re-previewed with their slippage metadata before return.

Before borrowing, read borrowableAmountFrom in the chosen accounting context. borrowableNow caps gross principal by live funds; borrowableCapacity is the economic collateral capacity and may be larger. minBorrowAmount protects gross principal before fees, not net proceeds. Show the expected net amount after protocol, REV, and prepaid source fees separately.

A holder acting for themselves needs no permission grant; a contract or operator borrowing on a holder's behalf needs OPEN_LOAN (37) from that holder. Collateral and source token are chain-local. Loan permissions can redirect funds or recovered collateral, so explain the specific authority before requesting a grant.

Before repaying, re-read loanOf and the source fee, compute a conservative ceiling, approve or permit the source token if needed, and simulate the exact collateral being returned. Native repayment sends the ceiling as value; the excess is refunded.

const { borrowableNow } = await getBorrowableAmount(publicClient, {
  chainId, revnetId, collateralCount, decimals, currency,
});
if (borrowableNow <= 0n) throw new Error("No funds available to borrow for this collateral");

const tx = buildBorrowTx({
  chainId, revnetId, token, collateralCount, beneficiary, holder,
  prepaidFeePercent,            // 25–500 (2.5%–50%, out of 1000)
  minBorrowAmount: slippageFloor(borrowableNow, 100n), // gross principal, 1% tolerance
});

Build each write from freshly resolved contracts, operator address, permission IDs, and project state, and simulate each chain on its own. A multisig proposal is pending until its Safe transaction executes; do not show success or invalidate state at proposal time.

Shop tiers sit outside stage economics. Whether transfers are paused is a per-stage flag fixed at launch (build721RulesetMetadata); whether the operator can add tiers, update metadata, change discounts, or mint depends on the hook's flags and the permissions the 721 overload granted.

const { request } = await publicClient.simulateContract({
  account: operator,
  address: hook,
  abi: jb721TiersHookAbi,
  functionName: "adjustTiers",
  args: [tierConfigurations, tiersToRemove],
});

const hash = await walletClient.writeContract(request);

A prepared move is not delivered value. Track its source sucker, peer sucker, token mapping, leaf index, beneficiary, proof, transport, fees, and status. CCIP and native bridges need different value and take different times; discover the payable value by simulating the exact call.

Accounting sync changes the displayed group backing without moving any local balance. Keep queued, in transit, claimable, claimed, failed, and retriable distinct.

const prepare = buildBridgePrepareTx({
  chainId, sucker, projectTokenCount, beneficiary,
  minTokensReclaimed, token, metadata,
});

const send = buildToRemoteTx({ chainId, sucker, token, value: bridgeFee });
const claim = buildBridgeClaimTx({ chainId: peerChainId, sucker: peer, claim: proof });
const sync = buildSyncAccountingDataTx({ chainId, sucker, value: syncFee });

RPC goes through Juicebox Center, an origin-allowlisted provider with no client-side key; wallets connect through injected, WalletConnect, Coinbase, Safe, and an embedded Para wallet that also provides the card on-ramp. Every write hook switches the wallet to the target chain before it does anything else.

Cross-chain authority is a real constraint: a Safe's L1 and L2 singletons differ, so a Safe that operates a revnet on one chain may not exist at the same address on another. Check before offering an operator action there.

Reviewed writeRelayr bundleSafe queueWallet configRelayr integration skill

• Shape: JBProjectMetadata: name, description, projectTagline, logoUri, coverImageUri, infoUri, payButton, payDisclosure, tags, twitter, telegram, discord, archived.
• Read: getProjectMetadata(publicClient, { jbControllerAddress, projectId }) resolves the uri and fetches it; ipfsUri / cidFromIpfsUri handle the encoding.
• Pin: this site pins JSON, images (25 MB), and media (500 MB) straight from the browser to Juicebox Center, which guards against empty files. The gateway is juicebox.center/ipfs/.
• Write: the operator updates the pointer with JBController.setUriOf (SET_PROJECT_URI).

Pinning at launchJuicebox Center IPFS client

Right before signing, refresh the reads that set bounds and permissions, rebuild, simulate with the real account, then decode the calldata and present it. After submission, keep wallet rejection, Safe proposal, inclusion, revert, and confirmed success as separate states. Only confirmed success invalidates reads.

This site enforces it mechanically: requireTransactionReview re-encodes the request after the user has seen it and throws if anything changed, and a build-time script rejects any wallet write outside the four reviewed hooks.

  fresh reads
    → pure builder
      → simulateContract with the real account
        → encode and decode the calldata, show it to the user
          → writeContract
            → waitForTransactionReceipt
              → success only on receipt.status === "success"

const tx = buildOperation(freshState, userInput);

const { request } = await publicClient.simulateContract({ ...tx, account });

const calldata = encodeFunctionData(tx);
const decoded = decodeFunctionData({ abi: tx.abi, data: calldata });
await review({ ...tx, calldata, decoded });

const hash = await walletClient.writeContract(request);
const receipt = await publicClient.waitForTransactionReceipt({ hash });
if (receipt.status !== "success") throw new Error("Transaction reverted");

• Env: NEXT_PUBLIC_SITE_URL, NEXT_PUBLIC_BENDYSTRAW_URL, NEXT_PUBLIC_TESTNET_BENDYSTRAW_URL, NEXT_PUBLIC_PARA_API_KEY, NEXT_PUBLIC_PARA_ENV, NEXT_PUBLIC_VERSION; WalletConnect and the on-ramp provider are optional. No RPC or IPFS keys live in the client.
• Tests: PR tests use fixtures; nothing in them reaches a wallet, an RPC, the index, or Relayr.

git clone https://github.com/mejango/revnet-money.git
cd revnet-money
# Install the Node version from .nvmrc with your Node version manager.
cp .env.example .env.local
npm ci
npm run dev
# Open http://localhost:3002

RepositoryTESTING.md

REVOwner is hard-wired as the project's ruleset data hook. On a payment it asks the revnet's 721 hook for its one tier split, then asks the buyback hook whether the pool is the better route, and returns at most those two specifications. On a cash out it returns the buyback specification, if any, and its own fee specification. deployFor has no field for a third-party hook, and hasMintPermissionFor answers yes only to REVLoans, the buyback hook, and registered suckers.

REVOwner.solREVDeployer.sol

Splits live in group 1 (RESERVED_TOKENS). Set the split's hook field to your contract's address. For an ERC-20 token, the controller grants an allowance: pull the tokens during the callback or the unconsumed amount is revoked and burned. For credits, it transfers them to the hook before the callback. A callback revert emits SplitHookReverted without blocking distribution; unpulled ERC-20 tokens are burned, while transferred credits remain at the hook.

// ERC-20-only fragment. Define CONTROLLER, PROJECT_ID, and PROJECT_TOKEN
// in your contract; inherit ReentrancyGuard and implement IERC165.
using SafeERC20 for IERC20;

function processSplitWith(JBSplitHookContext calldata context) external payable nonReentrant {
    if (msg.sender != address(CONTROLLER)) revert Unauthorized();
    if (context.projectId != PROJECT_ID) revert BadProject();
    if (context.groupId != 1 || address(context.split.hook) != address(this)) revert BadSplit();
    if (context.token == address(0) || context.token != PROJECT_TOKEN) revert BadToken();

    // ERC-20: pull it now; the allowance is revoked (and the remainder burned) after this call.
    IERC20(context.token).safeTransferFrom(msg.sender, address(this), context.amount);
    // ... do the thing: LP, vest, distribute, forward to another project.
}

• Funds: native value arrives as msg.value; ERC-20 forwarding uses an allowance to pull during the call, revoked afterwards. Fees depend on the path: an ordinary incoming payment hook is not automatically charged 2.5%. Validate the actual forwarded amount and use SafeERC20 for transfers.
• Two metadatas: hookMetadata is authored by the ruleset data hook; payerMetadata and cashOutMetadata originate with the caller. Authenticate the terminal, project, and expected data hook before relying on that origin, and validate both payloads. A legitimate shared terminal can call your hook for a different project.
• Metadata format: JBMetadataResolver: a reserved first word, then a table of 4-byte ids with word offsets, then 32-byte-aligned blobs. createMetadata(ids, datas), addToMetadata, getDataFor(id, metadata). Ids are getId(purpose, target) = bytes4(bytes20(target) ^ bytes20(keccak256(purpose))).
• noop: a specification with noop = true is informational; the terminal never calls it. That is how a hook reports a decision without receiving funds.
• Reentrancy: pay and cashOutTokensOf call hooks after recording state without a global reentrancy guard. Protect your hook's state and external calls; nonReentrant alone does not validate who called or which project is involved. Use override(ERC165, IERC165) for supportsInterface when inheriting both.

IJBRulesetDataHook.solIJBPayHook.solIJBCashOutHook.solJBMetadataResolver.soljb-pay-hook skilljb-cash-out-hook skill

npm i the packages you need and import by path (import "@rev-net/core-v6/src/REVDeployer.sol"). remappings.txt in every repo only maps forge-std; node_modules resolves the rest. That is also how the deploy artifacts record source names.

// Resolve the deployed contracts and construct the structs before this fragment.
// For matching chains, use the same explicit first-stage start and configuration hash.
(uint256 revnetId, IJB721TiersHook hook) = REV_DEPLOYER.deployFor{value: PROJECTS.creationFee()}({
    revnetId: 0,
    configuration: config,
    accountingContextsToAccept: contexts,
    suckerDeploymentConfiguration: suckers,
    tiered721HookConfiguration: shop,
    allowedPosts: new REVCroptopAllowedPost[](0)
});

A holder acting for themselves needs no grant. A contract acting for a holder needs JBPermissions.setPermissionsFor from that holder, scoped to the revnet (ROOT works but is far too broad). Every mutating call runs under a loan-specific reentrancy guard; the collateral is burned when the loan opens and minted again when it closes.

REVLoans.soljb-revloans skill

• Sizes: REVDeployer and REVOwner were split to fit EIP-170; the buyback hook dropped getters for the same reason. Check forge build --sizes early, and plan for library extraction if you are close.
• Bytecode parity: verify your deployment against the deploy-all-v6 artifacts rather than trusting a source match; linked libraries change the hash.

revnet-core-v6 testsTestBaseWorkflow

• Who is the payer: JBMultiTerminal records its ERC-2771-resolved caller as the payer. A wrapper can therefore be the payer even when a human funded it. Router integrations may probe originalPayer() for fee or refund attribution; that does not rewrite the terminal's payer context or authenticate a human. Set the token beneficiary explicitly.
• Buyback metadata is three words: the pay metadata under getId("pay") for the buyback hook decodes as (amountToSwapWith, minimumSwapAmountOut, skipSplits). Always encode all three; older hook versions tolerate a trailing third word, the current one requires it.
• hookMetadata is not yours: the buyback hook uses an internal tuple that is not an application input format. Caller metadata is untrusted, and hook metadata is only as trustworthy as the authenticated caller, project, and configured data hook. Do not decode it as a user-controlled request.
• Sucker cash outs: the registered sucker's source-chain cash out is untaxed and skips the launch lock, using local backing only. This permits bridge accounting. Tokens received by an ordinary holder on the destination do not acquire an exemption for a later cash out.
• Router terminal cold start: the router registry reverts accountingContextForTokenOf for projects below its threshold; it is not universally accepting. Probe with previewPayFor before assuming a route.
• The 7-day lock: a first stage whose start is already past at execution locks cash outs and loans for seven days on that chain. Relevant to Safe proposals and to scripted multichain launches.
• Burned allowance: a split hook that leaves allowance unspent loses those tokens; the controller burns the remainder.

Buyback hook sourcejb-terminal-selection skilljb-suckers skill

Fork-test against the current deployments. Then publish the addresses, source, transaction map, and a human-readable stage schedule so users can check your product against the contracts themselves. The audit page has prompts for a whole-system review and for a single transaction.

• Launch: the configuration round-trips through every supported ABI overload; a past nonzero first-stage start produces the documented seven-day lock; matching effective configuration, sender, salts, and deployment addresses produce the intended cross-chain token addresses.
• Payments: the chosen route's executable minimum is no worse than the alternatives shown; an empty pool falls back to issuance; a router route is probed, not assumed.
• Cash outs: the terminal or hook enforces the same minimum the confirmation shows, including at 0% fee-free surplus.
• Loans: only the loan permissions (37, 38, 39) are granted, scoped to the revnet; repayment ceilings cannot underpay the live obligation; partial repay mints the replacement NFT.
• Operator: no exposed call can change committed issuance, cuts, taxes, or split percentages; a Safe proposal is not success.
• Multichain: one chain's project, token, decimals, operator, or proof is never reused on another; delayed claims stay claimable.
• Hooks: reentrancy from a hostile hook or token, an under-pulling split hook, hostile payer metadata.

Audit prompts and source indexWhat users will checkReference web client