Merge pull request #269 from sprintertech/feat/netter

lastperson · web-flow · commit a7746d54b07b · 2026-07-02T15:19:36.000+07:00
Feat/netter
diff --git a/contracts/Netter.sol b/contracts/Netter.sol
@@ -0,0 +1,65 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+pragma solidity 0.8.28;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+import {AccessControl} from "@openzeppelin/contracts/access/AccessControl.sol";
+import {IOracle} from "./interfaces/IOracle.sol";
+import {IProcessor} from "./interfaces/IProcessor.sol";
+
+/// @title Netter — nets two Processor balances against each other at oracle fair value.
+/// @notice Instead of selling tokens on the open market, two processors can swap their
+///         accumulated foreign-asset balances through this contract, avoiding market slippage.
+///         The oracle ensures both sides carry equal value before any transfer is made.
+/// @author Sprinter
+contract Netter is AccessControl {
+    IOracle public immutable ORACLE;
+
+    bytes32 public constant CALLER_ROLE = "CALLER_ROLE";
+
+    error ZeroAddress();
+    error ValuesNotEqual();
+
+    event Netted(
+        address processorA,
+        address processorB,
+        uint256 amountFromA,
+        uint256 amountFromB
+    );
+
+    constructor(address oracle, address admin, address caller) {
+        require(oracle != address(0), ZeroAddress());
+        require(admin != address(0), ZeroAddress());
+        ORACLE = IOracle(oracle);
+        _grantRole(DEFAULT_ADMIN_ROLE, admin);
+        _grantRole(CALLER_ROLE, caller);
+    }
+
+    /// @notice Net processorA's balance of processorB's asset against processorB's balance of processorA's asset.
+    /// @param processorA Processor that holds amountFromA of processorB.TARGET_ASSET and will forward it.
+    /// @param processorB Processor that holds amountFromB of processorA.TARGET_ASSET and will forward it.
+    /// @param amountFromA Amount of processorB.TARGET_ASSET that processorA forwards.
+    /// @param amountFromB Amount of processorA.TARGET_ASSET that processorB forwards.
+    function net(
+        IProcessor processorA,
+        IProcessor processorB,
+        uint256 amountFromA,
+        uint256 amountFromB
+    ) external onlyRole(CALLER_ROLE) {
+        IERC20 assetA = processorA.TARGET_ASSET();
+        IERC20 assetB = processorB.TARGET_ASSET();
+
+        uint256 precision = 10**12;
+        uint256 valueA = ORACLE.getAssetValue(_toAssetId(assetA), amountFromB * precision);
+        uint256 valueB = ORACLE.getAssetValue(_toAssetId(assetB), amountFromA * precision);
+        require(valueA == valueB, ValuesNotEqual());
+
+        processorA.forwardAmount(assetB, amountFromA);
+        processorB.forwardAmount(assetA, amountFromB);
+
+        emit Netted(address(processorA), address(processorB), amountFromA, amountFromB);
+    }
+
+    function _toAssetId(IERC20 token) internal pure returns (bytes32) {
+        return bytes32(uint256(uint160(address(token))));
+    }
+}
diff --git a/contracts/Processor.sol b/contracts/Processor.sol
@@ -34,7 +34,7 @@ contract Processor is AccessControlUpgradeable, MulticallUpgradeable {
 
     bytes32 private constant STORAGE_LOCATION = 0x315f94a0eb28ebc9ade3d51c8bd7ef4c2011752d9ac5c2acc448e4822cfa1f00;
 
-    event Forwarded(address caller, IERC20 token);
+    event Forwarded(address caller, IERC20 token, uint256 amount);
     event Processed(address caller, IERC20 tokenIn, uint256 amountIn, uint256 amountOut);
     event MaxSlippageSet(uint256 maxSlippage);
     event AdminProcessed(address caller);
@@ -94,9 +94,13 @@ contract Processor is AccessControlUpgradeable, MulticallUpgradeable {
         _setMaxSlippage(_getStorage(), newMaxSlippage);
     }
 
-    function forward(IERC20 token) external onlyRole(CALLER_ROLE) {
-        _finalizeTransfer(token, token.balanceOf(address(this)));
-        emit Forwarded(msg.sender, token);
+    function forward(IERC20 token) external {
+        forwardAmount(token, token.balanceOf(address(this)));
+    }
+
+    function forwardAmount(IERC20 token, uint256 amount) public onlyRole(CALLER_ROLE) {
+        _finalizeTransfer(token, amount);
+        emit Forwarded(msg.sender, token, amount);
     }
 
     function redeem7540(IERC7540 token) external onlyRole(CALLER_ROLE) {
diff --git a/contracts/interfaces/IProcessor.sol b/contracts/interfaces/IProcessor.sol
@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: LGPL-3.0-only
+pragma solidity 0.8.28;
+
+import {IERC20} from "@openzeppelin/contracts/token/ERC20/IERC20.sol";
+
+interface IProcessor {
+    function TARGET_ASSET() external view returns (IERC20);
+    function forwardAmount(IERC20 token, uint256 amount) external;
+}
diff --git a/coverage-baseline.json b/coverage-baseline.json
@@ -1,6 +1,6 @@
 {
   "lines": "99.71",
-  "functions": "99.69",
-  "branches": "93.69",
+  "functions": "99.70",
+  "branches": "93.53",
   "statements": "99.71"
 }
diff --git a/package.json b/package.json
@@ -83,6 +83,8 @@
     "deploy-pyusd-stashdex-processor-ethereum-stage": "PROCESSOR_TOKEN=PYUSD DEPLOY_TYPE=STAGE hardhat run ./scripts/deployStashDexProcessor.ts --network ETHEREUM",
     "deploy-stashdex-ethereum": "hardhat run ./scripts/deployStashDex.ts --network ETHEREUM",
     "deploy-stashdex-ethereum-stage": "DEPLOY_TYPE=STAGE hardhat run ./scripts/deployStashDex.ts --network ETHEREUM",
+    "deploy-netter-ethereum": "hardhat run ./scripts/deployNetter.ts --network ETHEREUM",
+    "deploy-netter-ethereum-stage": "DEPLOY_TYPE=STAGE hardhat run ./scripts/deployNetter.ts --network ETHEREUM",
     "deploy-paxosoracle-ethereum": "hardhat run ./scripts/deployPaxosOracle.ts --network ETHEREUM",
     "deploy-paxosoracle-ethereum-stage": "DEPLOY_TYPE=STAGE hardhat run ./scripts/deployPaxosOracle.ts --network ETHEREUM",
     "upgrade-liquidityhub-basesepolia": "hardhat run ./scripts/upgradeLiquidityHub.ts --network BASE_SEPOLIA",
@@ -257,6 +259,8 @@
     "dry:deploy-pyusd-stashdex-processor-ethereum": "DRY_RUN=ETHEREUM VERIFY=false PROCESSOR_TOKEN=PYUSD ts-node --files ./scripts/deployStashDexProcessor.ts",
     "dry:deploy-stashdex-ethereum": "DRY_RUN=ETHEREUM VERIFY=false ts-node --files ./scripts/deployStashDex.ts",
     "dry:deploy-stashdex-ethereum-stage": "DRY_RUN=ETHEREUM DEPLOY_TYPE=STAGE VERIFY=false ts-node --files ./scripts/deployStashDex.ts",
+    "dry:deploy-netter-ethereum": "DRY_RUN=ETHEREUM VERIFY=false ts-node --files ./scripts/deployNetter.ts",
+    "dry:deploy-netter-ethereum-stage": "DRY_RUN=ETHEREUM DEPLOY_TYPE=STAGE VERIFY=false ts-node --files ./scripts/deployNetter.ts",
     "dry:upgrade-liquidityhub-basesepolia": "DRY_RUN=BASE_SEPOLIA VERIFY=false ts-node --files ./scripts/upgradeLiquidityHub.ts",
     "dry:upgrade-liquidityhub-base": "DRY_RUN=BASE VERIFY=false ts-node --files ./scripts/upgradeLiquidityHub.ts",
     "dry:upgrade-liquidityhub-base-stage": "DRY_RUN=BASE DEPLOY_TYPE=STAGE VERIFY=false ts-node --files ./scripts/upgradeLiquidityHub.ts",
diff --git a/scripts/deployNetter.ts b/scripts/deployNetter.ts
@@ -0,0 +1,85 @@
+import dotenv from "dotenv";
+dotenv.config();
+import hre from "hardhat";
+import {NonceManager} from "ethers";
+import {getVerifier, getHardhatNetworkConfig, getNetworkConfig, logDeployers} from "./helpers";
+import {resolveXAddress} from "../test/helpers";
+import {isSet, assert, assertAddress, DEFAULT_ADMIN_ROLE} from "./common";
+import {Netter} from "../typechain-types";
+import {Network, NetworkConfig} from "../network.config";
+
+export async function main() {
+  const [deployer] = await hre.ethers.getSigners();
+  const deployerWithNonce = new NonceManager(deployer);
+
+  assert(isSet(process.env.DEPLOY_ID), "DEPLOY_ID must be set");
+  const verifier = getVerifier(process.env.DEPLOY_ID);
+  console.log(`Deployment ID: ${process.env.DEPLOY_ID}`);
+  const id = "Netter";
+
+  let network: Network;
+  let config: NetworkConfig;
+  console.log("Deploying Netter");
+  ({network, config} = await getNetworkConfig());
+  if (!network) {
+    ({network, config} = await getHardhatNetworkConfig());
+  }
+  await logDeployers();
+
+  assert(config.StashDex, "StashDex must be in config");
+  assertAddress(config.Admin, "Admin must be an address");
+  assertAddress(config.RepayerCaller, "RepayerCaller must be an address");
+
+  const oracle = await resolveXAddress(config.StashDex.Oracle);
+
+  const netter = (await verifier.deployX(
+    "Netter",
+    deployerWithNonce,
+    {},
+    [oracle, config.Admin, config.RepayerCaller],
+    id,
+  )) as Netter;
+  console.log(`${id}: ${netter.target}`);
+
+  const uniqueProcessors = [
+    ...new Set(await Promise.all(config.StashDex.Routes.map(r => resolveXAddress(r.Processor)))),
+  ];
+
+  const CALLER_ROLE = hre.ethers.encodeBytes32String("CALLER_ROLE");
+
+  const granted: string[] = [];
+  const needsInstruction: string[] = [];
+
+  for (const processorAddr of uniqueProcessors) {
+    const processor = await hre.ethers.getContractAt("AccessControlUpgradeable", processorAddr);
+    if (await processor.hasRole(CALLER_ROLE, netter)) {
+      console.log(`CALLER_ROLE already granted to Netter on ${processorAddr} — skipping`);
+      continue;
+    }
+    if (await processor.hasRole(DEFAULT_ADMIN_ROLE, deployerWithNonce)) {
+      await processor.grantRole(CALLER_ROLE, netter);
+      granted.push(processorAddr);
+    } else {
+      needsInstruction.push(processorAddr);
+    }
+  }
+
+  if (granted.length > 0) {
+    console.log("Granted CALLER_ROLE to Netter on processors:");
+    console.table(granted.map(addr => ({processor: addr})));
+  }
+
+  if (needsInstruction.length > 0) {
+    const anyProcessor = await hre.ethers.getContractAt("AccessControlUpgradeable", needsInstruction[0]);
+    const calldata = (await anyProcessor.grantRole.populateTransaction(CALLER_ROLE, netter)).data;
+    console.log("NEXT STEPS — grant CALLER_ROLE to Netter on each processor:");
+    console.log(`Calldata: ${calldata}`);
+    console.table(needsInstruction.map(addr => ({processor: addr})));
+  }
+
+  await verifier.verify(process.env.VERIFY === "true");
+}
+
+if (process.env.SCRIPT_ENV !== "CI") {
+  main();
+}
diff --git a/scripts/test.ts b/scripts/test.ts
@@ -22,6 +22,7 @@ import {main as deployStashDex} from "./deployStashDex";
 import {main as deployStashDexProcessor} from "./deployStashDexProcessor";
 import {main as upgradeStashDexProcessor} from "./upgradeStashDexProcessor";
 import {main as upgradeStashDex} from "./upgradeStashDex";
+import {main as deployNetter} from "./deployNetter";
 
 async function main() {
   console.log("Test deploy.");
@@ -63,6 +64,8 @@ async function main() {
   await upgradeStashDexProcessor();
   console.log("Test upgradeStashDex.");
   await upgradeStashDex();
+  console.log("Test deployNetter.");
+  await deployNetter();
   console.log("Test deployStandaloneRepayer.");
   process.env.STANDALONE_REPAYER_ENV = "SparkStage";
   await deployStandaloneRepayer();
diff --git a/test/Netter.ts b/test/Netter.ts
@@ -0,0 +1,164 @@
+import hre from "hardhat";
+import {expect} from "chai";
+import {getContractAt, deploy, toBytes32, setupTests} from "./helpers";
+import {
+  TestUSDC, TestWETH, PaxosOracle, Processor, Netter, TransparentUpgradeableProxy,
+} from "../typechain-types";
+import {loadFixture} from "@nomicfoundation/hardhat-toolbox/network-helpers";
+import {addressToBytes32, ZERO_ADDRESS} from "../scripts/common";
+
+describe("Netter", function () {
+  setupTests();
+
+  const USDC = 10n ** 6n;
+  const WETH = 10n ** 18n;
+
+  const deployAll = async () => {
+    const [deployer, admin, caller, user, receiverA, receiverB] = await hre.ethers.getSigners();
+
+    const CALLER_ROLE = toBytes32("CALLER_ROLE");
+
+    const usdcRef = (await deploy("TestUSDC", deployer)) as TestUSDC;
+    const assetA = (await deploy("TestUSDC", deployer)) as TestUSDC;  // 6 decimals
+    const assetB = (await deploy("TestWETH", deployer)) as TestWETH;  // 18 decimals
+
+    const oracle = (await deploy("PaxosOracle", deployer, {}, admin, usdcRef, [
+      {assetId: addressToBytes32(assetA.target), decimals: 6},
+      {assetId: addressToBytes32(assetB.target), decimals: 18},
+    ])) as PaxosOracle;
+
+    const deployProcessor = async (asset: TestUSDC | TestWETH, receiver: typeof receiverA) => {
+      const impl = (await deploy("Processor", deployer, {}, asset, receiver, oracle)) as Processor;
+      const initData = (await impl.initialize.populateTransaction(admin, admin, admin)).data;
+      const proxy = (await deploy(
+        "TransparentUpgradeableProxy", deployer, {}, impl, admin, initData,
+      )) as TransparentUpgradeableProxy;
+      return (await getContractAt("Processor", proxy, deployer)) as Processor;
+    };
+
+    const processorA = await deployProcessor(assetA, receiverA);
+    const processorB = await deployProcessor(assetB, receiverB);
+
+    const netter = (await deploy("Netter", deployer, {}, oracle, admin, caller)) as Netter;
+
+    await processorA.connect(admin).grantRole(CALLER_ROLE, netter);
+    await processorB.connect(admin).grantRole(CALLER_ROLE, netter);
+
+    return {
+      deployer, admin, caller, user, receiverA, receiverB,
+      assetA, assetB, oracle, processorA, processorB, netter,
+    };
+  };
+
+  describe("constructor", function () {
+    it("reverts ZeroAddress when oracle is zero", async function () {
+      const {admin, caller, netter} = await loadFixture(deployAll);
+      await expect(deploy("Netter", admin, {}, ZERO_ADDRESS, admin, caller))
+        .to.be.revertedWithCustomError(netter, "ZeroAddress");
+    });
+
+    it("reverts ZeroAddress when admin is zero", async function () {
+      const {oracle, caller, netter} = await loadFixture(deployAll);
+      await expect(deploy("Netter", caller, {}, oracle, ZERO_ADDRESS, caller))
+        .to.be.revertedWithCustomError(netter, "ZeroAddress");
+    });
+
+    it("stores ORACLE and grants DEFAULT_ADMIN_ROLE and CALLER_ROLE", async function () {
+      const {netter, oracle, admin, caller} = await loadFixture(deployAll);
+      const DEFAULT_ADMIN_ROLE = await netter.DEFAULT_ADMIN_ROLE();
+      const CALLER_ROLE = await netter.CALLER_ROLE();
+
+      expect(await netter.ORACLE()).to.equal(oracle.target);
+      expect(await netter.hasRole(DEFAULT_ADMIN_ROLE, admin)).to.be.true;
+      expect(await netter.hasRole(CALLER_ROLE, caller)).to.be.true;
+      expect(await netter.hasRole(CALLER_ROLE, admin)).to.be.false;
+    });
+  });
+
+  describe("net", function () {
+    it("reverts AccessControlUnauthorizedAccount when caller lacks CALLER_ROLE", async function () {
+      const {netter, user, processorA, processorB} = await loadFixture(deployAll);
+      await expect(netter.connect(user).net(processorA, processorB, 1n, 1n))
+        .to.be.revertedWithCustomError(netter, "AccessControlUnauthorizedAccount");
+    });
+
+    it("reverts ValuesNotEqual when oracle values do not match", async function () {
+      const {netter, caller, processorA, processorB} = await loadFixture(deployAll);
+      await expect(netter.connect(caller).net(processorA, processorB, 3_000n * WETH + 1n, 3_000n * USDC))
+        .to.be.revertedWithCustomError(netter, "ValuesNotEqual");
+      await expect(netter.connect(caller).net(processorA, processorB, 3_000n * WETH - 1n, 3_000n * USDC))
+        .to.be.revertedWithCustomError(netter, "ValuesNotEqual");
+    });
+
+    it("forwards on both processors and emits Netted when values are equal", async function () {
+      const {netter, caller, processorA, processorB, assetA, assetB, receiverA, receiverB} =
+        await loadFixture(deployAll);
+
+      const amountFromA = 4_000n * WETH;
+      const amountFromB = 4_000n * USDC;
+
+      await assetB.mint(processorA, amountFromA);
+      await assetA.mint(processorB, amountFromB);
+
+      const tx = await netter.connect(caller).net(processorA, processorB, amountFromA, amountFromB);
+
+      await expect(tx).to.emit(netter, "Netted")
+        .withArgs(processorA.target, processorB.target, amountFromA, amountFromB);
+      await expect(tx).to.emit(processorA, "Forwarded")
+        .withArgs(netter.target, assetB.target, amountFromA);
+      await expect(tx).to.emit(processorB, "Forwarded")
+        .withArgs(netter.target, assetA.target, amountFromB);
+
+      expect(await assetB.balanceOf(processorA)).to.equal(0n);
+      expect(await assetA.balanceOf(processorB)).to.equal(0n);
+      expect(await assetB.balanceOf(receiverA)).to.equal(amountFromA);
+      expect(await assetA.balanceOf(receiverB)).to.equal(amountFromB);
+    });
+
+    it("forwards on both processors and emits Netted when values are equal, swapped order", async function () {
+      const {netter, caller, processorA, processorB, assetA, assetB, receiverA, receiverB} =
+        await loadFixture(deployAll);
+
+      const amountFromA = 4_000n * WETH;
+      const amountFromB = 4_000n * USDC;
+
+      await assetB.mint(processorA, amountFromA);
+      await assetA.mint(processorB, amountFromB);
+
+      const tx = await netter.connect(caller).net(processorB, processorA, amountFromB, amountFromA);
+
+      await expect(tx).to.emit(netter, "Netted")
+        .withArgs(processorB.target, processorA.target, amountFromB, amountFromA);
+      await expect(tx).to.emit(processorA, "Forwarded")
+        .withArgs(netter.target, assetB.target, amountFromA);
+      await expect(tx).to.emit(processorB, "Forwarded")
+        .withArgs(netter.target, assetA.target, amountFromB);
+
+      expect(await assetB.balanceOf(processorA)).to.equal(0n);
+      expect(await assetA.balanceOf(processorB)).to.equal(0n);
+      expect(await assetB.balanceOf(receiverA)).to.equal(amountFromA);
+      expect(await assetA.balanceOf(receiverB)).to.equal(amountFromB);
+    });
+
+    it("leaves unrelated balances untouched", async function () {
+      const {netter, caller, processorA, processorB, assetA, assetB, receiverA, receiverB} =
+        await loadFixture(deployAll);
+
+      const amountFromA = 4_000n * WETH;
+      const amountFromB = 4_000n * USDC;
+
+      // processorA also holds some assetA; processorB also holds some assetB
+      await assetB.mint(processorA, amountFromA);
+      await assetA.mint(processorA, 1_000n * USDC);
+      await assetA.mint(processorB, amountFromB);
+      await assetB.mint(processorB, 2_000n * WETH);
+
+      await netter.connect(caller).net(processorA, processorB, amountFromA, amountFromB);
+
+      expect(await assetA.balanceOf(processorA)).to.equal(1_000n * USDC);
+      expect(await assetB.balanceOf(processorB)).to.equal(2_000n * WETH);
+      expect(await assetA.balanceOf(receiverA)).to.equal(0n);
+      expect(await assetB.balanceOf(receiverB)).to.equal(0n);
+    });
+  });
+});
diff --git a/test/Processor.ts b/test/Processor.ts
diff --git a/test/StashDexProcessor.ts b/test/StashDexProcessor.ts

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"lines": "99.71",`
`3`		`- "functions": "99.69",`
`4`		`- "branches": "93.69",`
	`3`	`+ "functions": "99.70",`
	`4`	`+ "branches": "93.53",`
`5`	`5`	`"statements": "99.71"`
`6`	`6`	`}`