@arbitrum/nitro-contracts 1.2.1 → 2.0.0-beta.0

package/src/osp/OneStepProver0.sol

@@ -1,4 +1,4 @@
-// Copyright 2021-2022, Offchain Labs, Inc.
+// Copyright 2021-2023, Offchain Labs, Inc.
 // For license information, see https://github.com/OffchainLabs/nitro-contracts/blob/main/LICENSE
 // SPDX-License-Identifier: BUSL-1.1
 
@@ -11,6 +11,7 @@ import "../state/Deserialize.sol";
 import "./IOneStepProver.sol";
 
 contract OneStepProver0 is IOneStepProver {
+    using MachineLib for Machine;
     using MerkleProofLib for MerkleProof;
     using StackFrameLib for StackFrameWindow;
     using ValueLib for Value;
@@ -90,28 +91,11 @@ contract OneStepProver0 is IOneStepProver {
         bytes calldata
     ) internal pure {
         StackFrame memory frame = mach.frameStack.pop();
-        if (frame.returnPc.valueType == ValueType.REF_NULL) {
-            mach.status = MachineStatus.ERRORED;
-            return;
-        } else if (frame.returnPc.valueType != ValueType.INTERNAL_REF) {
-            revert("INVALID_RETURN_PC_TYPE");
-        }
-        uint256 data = frame.returnPc.contents;
-        uint32 pc = uint32(data);
-        uint32 func = uint32(data >> 32);
-        uint32 mod = uint32(data >> 64);
-        require(data >> 96 == 0, "INVALID_RETURN_PC_DATA");
-        mach.functionPc = pc;
-        mach.functionIdx = func;
-        mach.moduleIdx = mod;
+        mach.setPc(frame.returnPc);
     }
 
     function createReturnValue(Machine memory mach) internal pure returns (Value memory) {
-        uint256 returnData = 0;
-        returnData |= mach.functionPc;
-        returnData |= uint256(mach.functionIdx) << 32;
-        returnData |= uint256(mach.moduleIdx) << 64;
-        return Value({valueType: ValueType.INTERNAL_REF, contents: returnData});
+        return ValueLib.newPc(mach.functionPc, mach.functionIdx, mach.moduleIdx);
     }
 
     function executeCall(
@@ -157,6 +141,62 @@ contract OneStepProver0 is IOneStepProver {
         mach.functionPc = 0;
     }
 
+    function executeCrossModuleForward(
+        Machine memory mach,
+        Module memory,
+        Instruction calldata inst,
+        bytes calldata
+    ) internal pure {
+        // Push the return pc to the stack
+        mach.valueStack.push(createReturnValue(mach));
+
+        // Push caller's caller module info to the stack
+        StackFrame memory frame = mach.frameStack.peek();
+        mach.valueStack.push(ValueLib.newI32(frame.callerModule));
+        mach.valueStack.push(ValueLib.newI32(frame.callerModuleInternals));
+
+        // Jump to the target
+        uint32 func = uint32(inst.argumentData);
+        uint32 module = uint32(inst.argumentData >> 32);
+        require(inst.argumentData >> 64 == 0, "BAD_CROSS_MODULE_CALL_DATA");
+        mach.moduleIdx = module;
+        mach.functionIdx = func;
+        mach.functionPc = 0;
+    }
+
+    function executeCrossModuleInternalCall(
+        Machine memory mach,
+        Module memory mod,
+        Instruction calldata inst,
+        bytes calldata proof
+    ) internal pure {
+        // Get the target from the stack
+        uint32 internalIndex = uint32(inst.argumentData);
+        uint32 moduleIndex = mach.valueStack.pop().assumeI32();
+        Module memory calledMod;
+
+        MerkleProof memory modProof;
+        uint256 offset = 0;
+        (calledMod, offset) = Deserialize.module(proof, offset);
+        (modProof, offset) = Deserialize.merkleProof(proof, offset);
+        require(
+            modProof.computeRootFromModule(moduleIndex, calledMod) == mach.modulesRoot,
+            "CROSS_MODULE_INTERNAL_MODULES_ROOT"
+        );
+
+        // Push the return pc to the stack
+        mach.valueStack.push(createReturnValue(mach));
+
+        // Push caller module info to the stack
+        mach.valueStack.push(ValueLib.newI32(mach.moduleIdx));
+        mach.valueStack.push(ValueLib.newI32(mod.internalsOffset));
+
+        // Jump to the target
+        mach.moduleIdx = moduleIndex;
+        mach.functionIdx = internalIndex + calledMod.internalsOffset;
+        mach.functionPc = 0;
+    }
+
     function executeCallerModuleInternalCall(
         Machine memory mach,
         Module memory mod,
@@ -454,6 +494,10 @@ contract OneStepProver0 is IOneStepProver {
             impl = executeCall;
         } else if (opcode == Instructions.CROSS_MODULE_CALL) {
             impl = executeCrossModuleCall;
+        } else if (opcode == Instructions.CROSS_MODULE_FORWARD) {
+            impl = executeCrossModuleForward;
+        } else if (opcode == Instructions.CROSS_MODULE_INTERNAL_CALL) {
+            impl = executeCrossModuleInternalCall;
         } else if (opcode == Instructions.CALLER_MODULE_INTERNAL_CALL) {
             impl = executeCallerModuleInternalCall;
         } else if (opcode == Instructions.CALL_INDIRECT) {

package/src/osp/OneStepProverHostIo.sol

@@ -1,4 +1,4 @@
-// Copyright 2021-2022, Offchain Labs, Inc.
+// Copyright 2021-2024, Offchain Labs, Inc.
 // For license information, see https://github.com/OffchainLabs/nitro-contracts/blob/main/LICENSE
 // SPDX-License-Identifier: BUSL-1.1
 
@@ -6,6 +6,8 @@ pragma solidity ^0.8.0;
 
 import "../state/Value.sol";
 import "../state/Machine.sol";
+import "../state/MerkleProof.sol";
+import "../state/MultiStack.sol";
 import "../state/Deserialize.sol";
 import "../state/ModuleMemory.sol";
 import "./IOneStepProver.sol";
@@ -14,10 +16,13 @@ import "../bridge/IBridge.sol";
 
 contract OneStepProverHostIo is IOneStepProver {
     using GlobalStateLib for GlobalState;
+    using MachineLib for Machine;
     using MerkleProofLib for MerkleProof;
     using ModuleMemoryLib for ModuleMemory;
+    using MultiStackLib for MultiStack;
     using ValueLib for Value;
     using ValueStackLib for ValueStack;
+    using StackFrameLib for StackFrameWindow;
 
     uint256 private constant LEAF_SIZE = 32;
     uint256 private constant INBOX_NUM = 2;
@@ -52,7 +57,7 @@ contract OneStepProverHostIo is IOneStepProver {
             mach.status = MachineStatus.ERRORED;
             return;
         }
-        if (ptr + 32 > mod.moduleMemory.size || ptr % LEAF_SIZE != 0) {
+        if (!mod.moduleMemory.isValidLeaf(ptr)) {
             mach.status = MachineStatus.ERRORED;
             return;
         }
@@ -380,6 +385,103 @@ contract OneStepProverHostIo is IOneStepProver {
         mach.status = MachineStatus.FINISHED;
     }
 
+    function isPowerOfTwo(uint256 value) internal pure returns (bool) {
+        return value != 0 && (value & (value - 1) == 0);
+    }
+
+    function proveLastLeaf(
+        Machine memory mach,
+        uint256 offset,
+        bytes calldata proof
+    )
+        internal
+        pure
+        returns (
+            uint256 leaf,
+            MerkleProof memory leafProof,
+            MerkleProof memory zeroProof
+        )
+    {
+        string memory prefix = "Module merkle tree:";
+        bytes32 root = mach.modulesRoot;
+
+        {
+            Module memory leafModule;
+            uint32 leaf32;
+            (leafModule, offset) = Deserialize.module(proof, offset);
+            (leaf32, offset) = Deserialize.u32(proof, offset);
+            (leafProof, offset) = Deserialize.merkleProof(proof, offset);
+            leaf = uint256(leaf32);
+
+            bytes32 compRoot = leafProof.computeRootFromModule(leaf, leafModule);
+            require(compRoot == root, "WRONG_ROOT_FOR_LEAF");
+        }
+
+        // if tree is unbalanced, check that the next leaf is 0
+        bool balanced = isPowerOfTwo(leaf + 1);
+        if (balanced) {
+            require(1 << leafProof.counterparts.length == leaf + 1, "WRONG_LEAF");
+        } else {
+            (zeroProof, offset) = Deserialize.merkleProof(proof, offset);
+            bytes32 compRoot = zeroProof.computeRootUnsafe(leaf + 1, 0, prefix);
+            require(compRoot == root, "WRONG_ROOT_FOR_ZERO");
+        }
+
+        return (leaf, leafProof, zeroProof);
+    }
+
+    function executeLinkModule(
+        ExecutionContext calldata,
+        Machine memory mach,
+        Module memory mod,
+        Instruction calldata,
+        bytes calldata proof
+    ) internal pure {
+        string memory prefix = "Module merkle tree:";
+        bytes32 root = mach.modulesRoot;
+
+        uint256 pointer = mach.valueStack.pop().assumeI32();
+        if (!mod.moduleMemory.isValidLeaf(pointer)) {
+            mach.status = MachineStatus.ERRORED;
+            return;
+        }
+        (bytes32 userMod, uint256 offset, ) = mod.moduleMemory.proveLeaf(
+            pointer / LEAF_SIZE,
+            proof,
+            0
+        );
+
+        (uint256 leaf, , MerkleProof memory zeroProof) = proveLastLeaf(mach, offset, proof);
+
+        bool balanced = isPowerOfTwo(leaf + 1);
+        if (balanced) {
+            mach.modulesRoot = MerkleProofLib.growToNewRoot(root, leaf + 1, userMod, 0, prefix);
+        } else {
+            mach.modulesRoot = zeroProof.computeRootUnsafe(leaf + 1, userMod, prefix);
+        }
+
+        mach.valueStack.push(ValueLib.newI32(uint32(leaf + 1)));
+    }
+
+    function executeUnlinkModule(
+        ExecutionContext calldata,
+        Machine memory mach,
+        Module memory,
+        Instruction calldata,
+        bytes calldata proof
+    ) internal pure {
+        string memory prefix = "Module merkle tree:";
+
+        (uint256 leaf, MerkleProof memory leafProof, ) = proveLastLeaf(mach, 0, proof);
+
+        bool shrink = isPowerOfTwo(leaf);
+        if (shrink) {
+            mach.modulesRoot = leafProof.counterparts[leafProof.counterparts.length - 1];
+        } else {
+            mach.modulesRoot = leafProof.computeRootUnsafe(leaf, 0, prefix);
+        }
+    }
+
     function executeGlobalStateAccess(
         ExecutionContext calldata,
         Machine memory mach,
@@ -410,6 +512,93 @@ contract OneStepProverHostIo is IOneStepProver {
         mach.globalStateHash = state.hash();
     }
 
+    function executeNewCoThread(
+        ExecutionContext calldata,
+        Machine memory mach,
+        Module memory,
+        Instruction calldata,
+        bytes calldata
+    ) internal pure {
+        if (mach.recoveryPc != MachineLib.NO_RECOVERY_PC) {
+            // cannot create new cothread from inside cothread
+            mach.status = MachineStatus.ERRORED;
+            return;
+        }
+        mach.frameMultiStack.pushNew();
+        mach.valueMultiStack.pushNew();
+    }
+
+    function provePopCothread(MultiStack memory multi, bytes calldata proof) internal pure {
+        uint256 proofOffset = 0;
+        bytes32 newInactiveCoThread;
+        bytes32 newRemaining;
+        (newInactiveCoThread, proofOffset) = Deserialize.b32(proof, proofOffset);
+        (newRemaining, proofOffset) = Deserialize.b32(proof, proofOffset);
+        if (newInactiveCoThread == MultiStackLib.NO_STACK_HASH) {
+            require(newRemaining == bytes32(0), "WRONG_COTHREAD_EMPTY");
+            require(multi.remainingHash == bytes32(0), "WRONG_COTHREAD_EMPTY");
+        } else {
+            require(
+                keccak256(abi.encodePacked("cothread:", newInactiveCoThread, newRemaining)) ==
+                    multi.remainingHash,
+                "WRONG_COTHREAD_POP"
+            );
+        }
+        multi.remainingHash = newRemaining;
+        multi.inactiveStackHash = newInactiveCoThread;
+    }
+
+    function executePopCoThread(
+        ExecutionContext calldata,
+        Machine memory mach,
+        Module memory,
+        Instruction calldata,
+        bytes calldata proof
+    ) internal pure {
+        if (mach.recoveryPc != MachineLib.NO_RECOVERY_PC) {
+            // cannot pop cothread from inside cothread
+            mach.status = MachineStatus.ERRORED;
+            return;
+        }
+        if (mach.frameMultiStack.inactiveStackHash == MultiStackLib.NO_STACK_HASH) {
+            // cannot pop cothread if there isn't one
+            mach.status = MachineStatus.ERRORED;
+            return;
+        }
+        provePopCothread(mach.valueMultiStack, proof);
+        provePopCothread(mach.frameMultiStack, proof[64:]);
+    }
+
+    function executeSwitchCoThread(
+        ExecutionContext calldata,
+        Machine memory mach,
+        Module memory,
+        Instruction calldata inst,
+        bytes calldata
+    ) internal pure {
+        if (mach.frameMultiStack.inactiveStackHash == MultiStackLib.NO_STACK_HASH) {
+            // cannot switch cothread if there isn't one
+            mach.status = MachineStatus.ERRORED;
+            return;
+        }
+        if (inst.argumentData == 0) {
+            if (mach.recoveryPc == MachineLib.NO_RECOVERY_PC) {
+                // switching to main thread, from main thread
+                mach.status = MachineStatus.ERRORED;
+                return;
+            }
+            mach.recoveryPc = MachineLib.NO_RECOVERY_PC;
+        } else {
+            if (mach.recoveryPc != MachineLib.NO_RECOVERY_PC) {
+                // switching from cothread to cothread
+                mach.status = MachineStatus.ERRORED;
+                return;
+            }
+            mach.setRecoveryFromPc(uint32(inst.argumentData));
+        }
+        mach.switchCoThreadStacks();
+    }
+
     function executeOneStep(
         ExecutionContext calldata execCtx,
         Machine calldata startMach,
@@ -441,6 +630,16 @@ contract OneStepProverHostIo is IOneStepProver {
             impl = executeReadInboxMessage;
         } else if (opcode == Instructions.HALT_AND_SET_FINISHED) {
             impl = executeHaltAndSetFinished;
+        } else if (opcode == Instructions.LINK_MODULE) {
+            impl = executeLinkModule;
+        } else if (opcode == Instructions.UNLINK_MODULE) {
+            impl = executeUnlinkModule;
+        } else if (opcode == Instructions.NEW_COTHREAD) {
+            impl = executeNewCoThread;
+        } else if (opcode == Instructions.POP_COTHREAD) {
+            impl = executePopCoThread;
+        } else if (opcode == Instructions.SWITCH_COTHREAD) {
+            impl = executeSwitchCoThread;
         } else {
             revert("INVALID_MEMORY_OPCODE");
         }

package/src/osp/OneStepProverMemory.sol

@@ -19,13 +19,6 @@ contract OneStepProverMemory is IOneStepProver {
     uint256 private constant LEAF_SIZE = 32;
     uint64 private constant PAGE_SIZE = 65536;
 
-    function pullLeafByte(bytes32 leaf, uint256 idx) internal pure returns (uint8) {
-        require(idx < LEAF_SIZE, "BAD_PULL_LEAF_BYTE_IDX");
-        // Take into account that we are casting the leaf to a big-endian integer
-        uint256 leafShift = (LEAF_SIZE - 1 - idx) * 8;
-        return uint8(uint256(leaf) >> leafShift);
-    }
-
     function setLeafByte(
         bytes32 oldLeaf,
         uint256 idx,
@@ -109,35 +102,13 @@ contract OneStepProverMemory is IOneStepProver {
             revert("INVALID_MEMORY_LOAD_OPCODE");
         }
 
-        // Neither of these can overflow as they're computed with much less than 256 bit integers.
-        uint256 startIdx = inst.argumentData + mach.valueStack.pop().assumeI32();
-        if (startIdx + readBytes > mod.moduleMemory.size) {
+        uint256 index = inst.argumentData + mach.valueStack.pop().assumeI32();
+        (bool err, uint256 value, ) = mod.moduleMemory.load(index, readBytes, proof, 0);
+        if (err) {
             mach.status = MachineStatus.ERRORED;
             return;
         }
-
-        uint256 proofOffset = 0;
-        uint256 lastProvedLeafIdx = ~uint256(0);
-        bytes32 lastProvedLeafContents;
-        uint64 readValue;
-        for (uint256 i = 0; i < readBytes; i++) {
-            uint256 idx = startIdx + i;
-            uint256 leafIdx = idx / LEAF_SIZE;
-            if (leafIdx != lastProvedLeafIdx) {
-                // This hits the stack size if we phrase it as mod.moduleMemory.proveLeaf(...)
-                (lastProvedLeafContents, proofOffset, ) = ModuleMemoryLib.proveLeaf(
-                    mod.moduleMemory,
-                    leafIdx,
-                    proof,
-                    proofOffset
-                );
-                lastProvedLeafIdx = leafIdx;
-            }
-            uint256 indexWithinLeaf = idx % LEAF_SIZE;
-            readValue |=
-                uint64(pullLeafByte(lastProvedLeafContents, indexWithinLeaf)) <<
-                uint64(i * 8);
-        }
+        uint64 readValue = uint64(value);
 
         if (signed) {
             // Go down to the original uint size, change to signed, go up to correct size, convert back to unsigned

package/src/precompiles/ArbDebug.sol

@@ -37,6 +37,8 @@ interface ArbDebug {
 
     function customRevert(uint64 number) external pure;
 
+    function panic() external;
+
     function legacyError() external pure;
 
     error Custom(uint64, string, bool);

package/src/precompiles/ArbOwner.sol

@@ -1,16 +1,18 @@
-// Copyright 2021-2022, Offchain Labs, Inc.
+// Copyright 2021-2024, Offchain Labs, Inc.
 // For license information, see https://github.com/OffchainLabs/nitro-contracts/blob/main/LICENSE
 // SPDX-License-Identifier: BUSL-1.1
 
 pragma solidity >=0.4.21 <0.9.0;
 
-/// @title Provides owners with tools for managing the rollup.
-/// @notice Calls by non-owners will always revert.
-/// Most of Arbitrum Classic's owner methods have been removed since they no longer make sense in Nitro:
-/// - What were once chain parameters are now parts of ArbOS's state, and those that remain are set at genesis.
-/// - ArbOS upgrades happen with the rest of the system rather than being independent
-/// - Exemptions to address aliasing are no longer offered. Exemptions were intended to support backward compatibility for contracts deployed before aliasing was introduced, but no exemptions were ever requested.
-/// Precompiled contract that exists in every Arbitrum chain at 0x0000000000000000000000000000000000000070.
+/**
+ * @title Provides owners with tools for managing the rollup.
+ * @notice Calls by non-owners will always revert.
+ * Most of Arbitrum Classic's owner methods have been removed since they no longer make sense in Nitro:
+ * - What were once chain parameters are now parts of ArbOS's state, and those that remain are set at genesis.
+ * - ArbOS upgrades happen with the rest of the system rather than being independent
+ * - Exemptions to address aliasing are no longer offered. Exemptions were intended to support backward compatibility for contracts deployed before aliasing was introduced, but no exemptions were ever requested.
+ * Precompiled contract that exists in every Arbitrum chain at 0x0000000000000000000000000000000000000070.
+ **/
 interface ArbOwner {
     /// @notice Add account as a chain owner
     function addChainOwner(address newOwner) external;
@@ -90,9 +92,49 @@ interface ArbOwner {
     /// @notice Releases surplus funds from L1PricerFundsPoolAddress for use
     function releaseL1PricerSurplusFunds(uint256 maxWeiToRelease) external returns (uint256);
 
+    /// @notice Sets the amount of ink 1 gas buys
+    /// @param price the conversion rate (must fit in a uint24)
+    function setInkPrice(uint32 price) external;
+
+    /// @notice Sets the maximum depth (in wasm words) a wasm stack may grow
+    function setWasmMaxStackDepth(uint32 depth) external;
+
+    /// @notice Sets the number of free wasm pages a tx gets
+    function setWasmFreePages(uint16 pages) external;
+
+    /// @notice Sets the base cost of each additional wasm page
+    function setWasmPageGas(uint16 gas) external;
+
+    /// @notice Sets the maximum number of pages a wasm may allocate
+    function setWasmPageLimit(uint16 limit) external;
+
+    /// @notice Sets the minimum costs to invoke a program
+    /// @param gas amount of gas paid in increments of 256 when not the program is not cached
+    /// @param cached amount of gas paid in increments of 64 when the program is cached
+    function setWasmMinInitGas(uint8 gas, uint16 cached) external;
+
+    /// @notice Sets the linear adjustment made to program init costs.
+    /// @param percent the adjustment (100% = no adjustment).
+    function setWasmInitCostScalar(uint64 percent) external;
+
+    /// @notice Sets the number of days after which programs deactivate
+    function setWasmExpiryDays(uint16 _days) external;
+
+    /// @notice Sets the age a program must be to perform a keepalive
+    function setWasmKeepaliveDays(uint16 _days) external;
+
+    /// @notice Sets the number of extra programs ArbOS caches during a given block
+    function setWasmBlockCacheSize(uint16 count) external;
+
+    /// @notice Adds account as a wasm cache manager
+    function addWasmCacheManager(address manager) external;
+
+    /// @notice Removes account from the list of wasm cache managers
+    function removeWasmCacheManager(address manager) external;
+
     /// @notice Sets serialized chain config in ArbOS state
     function setChainConfig(string calldata chainConfig) external;
 
-    // Emitted when a successful call is made to this precompile
+    /// Emitted when a successful call is made to this precompile
     event OwnerActs(bytes4 indexed method, address indexed owner, bytes data);
 }

package/src/precompiles/ArbWasm.sol

@@ -0,0 +1,119 @@
+// Copyright 2022-2024, Offchain Labs, Inc.
+// For license information, see https://github.com/OffchainLabs/nitro/blob/master/LICENSE
+// SPDX-License-Identifier: BUSL-1.1
+
+pragma solidity >=0.4.21 <0.9.0;
+
+/**
+ * @title Methods for managing user programs
+ * @notice Precompiled contract that exists in every Arbitrum chain at 0x0000000000000000000000000000000000000071.
+ */
+interface ArbWasm {
+    /// @notice Activate a wasm program
+    /// @param program the program to activate
+    /// @return version the stylus version the program was activated against
+    /// @return dataFee the data fee paid to store the activated program
+    function activateProgram(address program)
+        external
+        payable
+        returns (uint16 version, uint256 dataFee);
+
+    /// @notice Gets the latest stylus version
+    /// @return version the stylus version
+    function stylusVersion() external view returns (uint16 version);
+
+    /// @notice Gets the stylus version the program with codehash was most recently activated against
+    /// @return version the program version (reverts for EVM contracts)
+    function codehashVersion(bytes32 codehash) external view returns (uint16 version);
+
+    /// @notice Extends a program's expiration date.
+    /// Reverts if too soon or if the program is not up to date.
+    function codehashKeepalive(bytes32 codehash) external payable;
+
+    /// @notice Gets a program's asm size.
+    /// Reverts if program is not active.
+    /// @return size the size in bytes
+    function codehashAsmSize(bytes32 codehash) external view returns (uint32 size);
+
+    /// @notice Gets the stylus version the program was most recently activated against
+    /// @return version the program version (reverts for EVM contracts)
+    function programVersion(address program) external view returns (uint16 version);
+
+    /// @notice Gets the cost to invoke the program
+    /// @return gas the amount of gas
+    /// @return gasWhenCached the amount of gas if the program was recently used
+    function programInitGas(address program)
+        external
+        view
+        returns (uint64 gas, uint64 gasWhenCached);
+
+    /// @notice Gets the memory footprint of the program at the given address in pages
+    /// @return footprint the memory footprint of program in pages (reverts for EVM contracts)
+    function programMemoryFootprint(address program) external view returns (uint16 footprint);
+
+    /// @notice Gets the amount of time remaining until the program expires
+    /// @return _secs the time left in seconds (reverts for EVM contracts)
+    function programTimeLeft(address program) external view returns (uint64 _secs);
+
+    /// @notice Gets the conversion rate between gas and ink
+    /// @return price the amount of ink 1 gas buys
+    function inkPrice() external view returns (uint32 price);
+
+    /// @notice Gets the wasm stack size limit
+    /// @return depth the maximum depth (in wasm words) a wasm stack may grow
+    function maxStackDepth() external view returns (uint32 depth);
+
+    /// @notice Gets the number of free wasm pages a program gets
+    /// @return pages the number of wasm pages (2^16 bytes)
+    function freePages() external view returns (uint16 pages);
+
+    /// @notice Gets the base cost of each additional wasm page (2^16 bytes)
+    /// @return gas base amount of gas needed to grow another wasm page
+    function pageGas() external view returns (uint16 gas);
+
+    /// @notice Gets the ramp that drives exponential memory costs
+    /// @return ramp bits representing the floating point value
+    function pageRamp() external view returns (uint64 ramp);
+
+    /// @notice Gets the maximum number of pages a wasm may allocate
+    /// @return limit the number of pages
+    function pageLimit() external view returns (uint16 limit);
+
+    /// @notice Gets the minimum costs to invoke a program
+    /// @return gas amount of gas in increments of 256 when not cached
+    /// @return cached amount of gas in increments of 64 when cached
+    function minInitGas() external view returns (uint8 gas, uint8 cached);
+
+    /// @notice Gets the linear adjustment made to program init costs.
+    /// @return percent the adjustment (100% = no adjustment).
+    function initCostScalar() external view returns (uint64 percent);
+
+    /// @notice Gets the number of days after which programs deactivate
+    /// @return _days the number of days
+    function expiryDays() external view returns (uint16 _days);
+
+    /// @notice Gets the age a program must be to perform a keepalive
+    /// @return _days the number of days
+    function keepaliveDays() external view returns (uint16 _days);
+
+    /// @notice Gets the number of extra programs ArbOS caches during a given block.
+    /// @return count the number of same-block programs.
+    function blockCacheSize() external view returns (uint16 count);
+
+    event ProgramActivated(
+        bytes32 indexed codehash,
+        bytes32 moduleHash,
+        address program,
+        uint256 dataFee,
+        uint16 version
+    );
+    event ProgramLifetimeExtended(bytes32 indexed codehash, uint256 dataFee);
+
+    error ProgramNotWasm();
+    error ProgramNotActivated();
+    error ProgramNeedsUpgrade(uint16 version, uint16 stylusVersion);
+    error ProgramExpired(uint64 ageInSeconds);
+    error ProgramUpToDate();
+    error ProgramKeepaliveTooSoon(uint64 ageInSeconds);
+    error ProgramInsufficientValue(uint256 have, uint256 want);
+}

package/src/precompiles/ArbWasmCache.sol

@@ -0,0 +1,33 @@
+// Copyright 2022-2024, Offchain Labs, Inc.
+// For license information, see https://github.com/OffchainLabs/nitro/blob/master/LICENSE
+// SPDX-License-Identifier: BUSL-1.1
+
+pragma solidity >=0.4.21 <0.9.0;
+
+/**
+ * @title Methods for managing Stylus caches
+ * @notice Precompiled contract that exists in every Arbitrum chain at 0x0000000000000000000000000000000000000072.
+ */
+interface ArbWasmCache {
+    /// @notice See if the user is a cache manager.
+    function isCacheManager(address manager) external view returns (bool);
+
+    /// @notice Retrieve all address managers.
+    /// @return managers the list of managers.
+    function allCacheManagers() external view returns (address[] memory managers);
+
+    /// @notice Caches all programs with the given codehash.
+    /// @notice Reverts if the programs have expired.
+    /// @notice Caller must be a cache manager or chain owner.
+    /// @notice If you're looking for how to bid for position, interact with the chain's cache manager contract.
+    function cacheCodehash(bytes32 codehash) external;
+
+    /// @notice Evicts all programs with the given codehash.
+    /// @notice Caller must be a cache manager or chain owner.
+    function evictCodehash(bytes32 codehash) external;
+
+    /// @notice Gets whether a program is cached. Note that the program may be expired.
+    function codehashIsCached(bytes32 codehash) external view returns (bool);
+
+    event UpdateProgramCache(address indexed manager, bytes32 indexed codehash, bool cached);
+}