@coti-io/coti-contracts 1.2.0 → 1.3.1

package/contracts/mocks/utils/mpc/TransferWithAllowance128TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/TransferWithAllowance256TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/TransferWithAllowance64_16TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/TransferWithAllowance64_32TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/TransferWithAllowance64_64TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/TransferWithAllowance64_8TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/TransferWithAllowanceScalarTestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/TransferWithAllowanceTestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/ValidateCiphertext128TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/utils/mpc/ValidateCiphertext256TestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 
@@ -51,7 +51,7 @@ contract ValidateCiphertext256TestsContract {
         gtUint256 validatedValue = MpcCore.validateCiphertext(input);
         
         // Add 1 to the value
-        gtUint256 one = MpcCore.setPublic256(1);
+        gtUint256 one = MpcCore.setPublic256(uint256(1));
         gtUint256 result = MpcCore.add(validatedValue, one);
         
         // Decrypt and return

package/contracts/mocks/utils/mpc/ValidateCiphertextTestsContract.sol

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../utils/mpc/MpcCore.sol";
 

package/contracts/mocks/wallet/PrivateERC20Wallet/PrivateERC20WalletMock.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../../../token/PrivateERC20/IPrivateERC20.sol";
 import "../../../utils/mpc/MpcCore.sol";

package/contracts/node/CotiNodeRewards.sol

@@ -1,8 +1,8 @@
 // SPDX-License-Identifier: MIT
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import {Ownable} from "@openzeppelin/contracts/access/Ownable.sol";
-import {ReentrancyGuard} from "@openzeppelin/contracts/security/ReentrancyGuard.sol";
+import {ReentrancyGuard} from "@openzeppelin/contracts/utils/ReentrancyGuard.sol";
 
 /**
  * @title CotiNodeRewards
@@ -59,7 +59,7 @@ contract CotiNodeRewards is Ownable, ReentrancyGuard {
     error AlreadyRewardedInEpoch(address wallet, uint256 epoch);
     error InvalidEpoch(uint256 epoch);
 
-    constructor() Ownable() {
+    constructor() Ownable(msg.sender) {
         eligibilityRules[RULE_PLATFORM_COTI_AMOUNT] = 100_000 * 10**DECIMALS_COTI;   // 100k COTI
         eligibilityRules[RULE_PLATFORM_USDC_AMOUNT] = 50_000 * 10**DECIMALS_USDC;    // 50k USDC
         eligibilityRules[RULE_FULL_NODE_UPTIME_PERCENTAGE_THRESHOLD] = 98;          // 98%

package/contracts/node/SoulboundNodeNFT.sol

@@ -67,7 +67,7 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
     /// @notice Last minted token ID (starts at 0, first mint = 1)
     uint256 public nextTokenId;
 
-    /// @notice Maximum length (in bytes) for nodeName and socialURL
+    /// @notice Maximum length (in bytes) for name and socialURL
     uint256 public constant MAX_TEXT_BYTES = 150;
 
     /**
@@ -78,8 +78,8 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
 
     /// @notice Node-specific metadata stored on-chain
     struct NodeData {
-        string nodeName; // required
-        string nodeImageURI; // optional (ipfs:// or https://)
+        string name; // required
+        string image; // optional (ipfs:// or https://)
         string socialURL; // optional
         bool isHot; // true = hot node, false = cold node
     }
@@ -91,8 +91,8 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
     event NodeMinted(
         address indexed to,
         uint256 indexed tokenId,
-        string nodeName,
-        string nodeImageURI,
+        string name,
+        string image,
         string socialURL
     );
 
@@ -121,8 +121,7 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
         string memory name_,
         string memory symbol_,
         address initialOwner
-    ) ERC721(name_, symbol_) {
-        _transferOwnership(initialOwner);
+    ) ERC721(name_, symbol_) Ownable(initialOwner) {
         mintPaused = false;
     }
 
@@ -187,8 +186,8 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
     /**
      * @notice Mint a new soulbound Node NFT
      * @param to Recipient address
-     * @param nodeName Node name (required, <=150 bytes)
-     * @param nodeImageURI Optional image URI
+     * @param name Node name (required, <=150 bytes)
+     * @param image Optional image URI
      * @param socialURL Optional social URL (<=150 bytes)
      * @return tokenId The ID of the newly minted token
      * @dev Restrictions:
@@ -199,22 +198,22 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
      *  - Minting is paused (MintPaused)
      *  - to is the zero address (InvalidRecipient)
      *  - to already owns an NFT (AlreadyOwnsNodeNFT)
-     *  - nodeName is empty (NodeNameRequired)
-     *  - nodeName exceeds MAX_TEXT_BYTES (NodeNameTooLong)
+     *  - name is empty (NodeNameRequired)
+     *  - name exceeds MAX_TEXT_BYTES (NodeNameTooLong)
      *  - socialURL exceeds MAX_TEXT_BYTES (SocialURLTooLong)
      * @dev Emits Locked and NodeMinted events
      */
     function mintNode(
         address to,
-        string calldata nodeName,
-        string calldata nodeImageURI,
+        string calldata name,
+        string calldata image,
         string calldata socialURL
     ) external onlyOwner returns (uint256 tokenId) {
         if (mintPaused) revert MintPaused();
         if (to == address(0)) revert InvalidRecipient();
         if (balanceOf(to) != 0) revert AlreadyOwnsNodeNFT();
-        if (bytes(nodeName).length == 0) revert NodeNameRequired();
-        if (bytes(nodeName).length > MAX_TEXT_BYTES) revert NodeNameTooLong();
+        if (bytes(name).length == 0) revert NodeNameRequired();
+        if (bytes(name).length > MAX_TEXT_BYTES) revert NodeNameTooLong();
         if (bytes(socialURL).length > MAX_TEXT_BYTES) revert SocialURLTooLong();
 
         tokenId = ++nextTokenId;
@@ -222,21 +221,21 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
         _safeMint(to, tokenId);
 
         _nodeData[tokenId] = NodeData({
-            nodeName: nodeName,
-            nodeImageURI: nodeImageURI,
+            name: name,
+            image: image,
             socialURL: socialURL,
             // Default new nodes to hot; can be updated later via setNodeHotStatus
             isHot: true
         });
 
         emit Locked(tokenId);
-        emit NodeMinted(to, tokenId, nodeName, nodeImageURI, socialURL);
+        emit NodeMinted(to, tokenId, name, image, socialURL);
     }
 
     /**
      * @notice Get node metadata for a token
      * @param tokenId Token ID to query
-     * @return NodeData struct containing nodeName, nodeImageURI, and socialURL
+     * @return NodeData struct containing name, image, and socialURL
      * @dev Reverts if the token does not exist (NonexistentToken)
      */
     function nodeData(uint256 tokenId) external view returns (NodeData memory) {
@@ -295,7 +294,7 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
         if (msg.sender != tokenOwner && msg.sender != owner())
             revert NotAuthorized();
 
-        _nodeData[tokenId].nodeImageURI = newImageURI;
+        _nodeData[tokenId].image = newImageURI;
         emit ImageURIUpdated(tokenId, newImageURI);
     }
 
@@ -349,7 +348,7 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
         if (bytes(newNodeName).length > MAX_TEXT_BYTES)
             revert NodeNameTooLong();
 
-        _nodeData[tokenId].nodeName = newNodeName;
+        _nodeData[tokenId].name = newNodeName;
         emit NodeNameUpdated(tokenId, newNodeName);
     }
 
@@ -456,16 +455,16 @@ contract SoulboundNodeNFT is ERC721, Ownable, IERC5192 {
 
         string memory attributes = string.concat(
             '[{"trait_type":"Node name","value":"',
-            _escapeJSON(d.nodeName),
+            _escapeJSON(d.name),
             '"}',
             ',{"trait_type":"Social URL","value":"',
             _escapeJSON(d.socialURL),
             '"}]'
         );
 
-        string memory imagePart = bytes(d.nodeImageURI).length == 0
+        string memory imagePart = bytes(d.image).length == 0
             ? ""
-            : string.concat(',"image":"', _escapeJSON(d.nodeImageURI), '"');
+            : string.concat(',"image":"', _escapeJSON(d.image), '"');
 
         string memory json = string.concat(
             '{"name":"Node #',

package/contracts/onboard/AccountOnboard.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity ^0.8.19;
+pragma solidity ^0.8.20;
 
 import "../utils/mpc/MpcCore.sol";
 

package/contracts/oracle/CotiPriceConsumer.sol

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+import "./IStdReference.sol";
+
+/**
+ * @title CotiPriceConsumer
+ * @notice Retrieves token/USD prices from the Band Protocol oracle.
+ * @dev All prices returned by Band Protocol are scaled by 1e18.
+ *      For example, a rate of 50000000000000000 means $0.05.
+ */
+contract CotiPriceConsumer {
+    /// @notice Band Protocol StdReferenceProxy on COTI .
+    IStdReference public immutable ref;
+
+    /// @notice Maximum acceptable age (in seconds) for oracle data before it is considered stale.
+    uint256 public maxStaleness;
+
+    /// @notice Emitted when the staleness threshold is updated.
+    event MaxStalenessUpdated(uint256 oldValue, uint256 newValue);
+
+    /// @notice Thrown when the oracle data is older than the allowed staleness window.
+    error StaleOracleData(uint256 lastUpdated, uint256 threshold);
+
+    address public owner;
+
+    /// @notice Minimum allowed staleness threshold (1 hour).
+    uint256 public constant MIN_STALENESS = 1 hours;
+
+    /// @notice Thrown when the staleness value is below the minimum.
+    error StalenessTooLow(uint256 provided, uint256 minimum);
+
+    modifier onlyOwner() {
+        require(msg.sender == owner, "CotiPriceConsumer: caller is not the owner");
+        _;
+    }
+
+    /**
+     * @param _ref          Address of the Band Protocol StdReferenceProxy contract.
+     * @param _maxStaleness Maximum acceptable data age in seconds (0 = no staleness check).
+     */
+    constructor(address _ref, uint256 _maxStaleness) {
+        require(_ref != address(0), "CotiPriceConsumer: zero ref address");
+        if (_maxStaleness < MIN_STALENESS) revert StalenessTooLow(_maxStaleness, MIN_STALENESS);
+        ref = IStdReference(_ref);
+        maxStaleness = _maxStaleness;
+        owner = msg.sender;
+    }
+
+    /// @notice Returns the rate, last update timestamp, and current block timestamp for any base/USD pair.
+    /// @return rate           The price scaled by 1e18
+    /// @return lastUpdated    Block timestamp when the oracle data was last updated
+    /// @return blockTimestamp The current block.timestamp
+    function getPriceWithMeta(string calldata _base) external view returns (uint256 rate, uint256 lastUpdated, uint256 blockTimestamp) {
+        IStdReference.ReferenceData memory data = _getPrice(_base);
+        rate = data.rate;
+        lastUpdated = data.lastUpdatedBase;
+        blockTimestamp = block.timestamp;
+    }
+
+
+    // ──────────────────────────────────────────────────────────────────────
+    //  Internal helper
+    // ──────────────────────────────────────────────────────────────────────
+
+    /**
+     * @dev Queries the Band oracle for `_base`/USD and optionally enforces staleness.
+     */
+    function _getPrice(string memory _base) internal view returns (IStdReference.ReferenceData memory data) {
+        data = ref.getReferenceData(_base, "USD");
+
+        uint256 threshold = block.timestamp - maxStaleness;
+        if (data.lastUpdatedBase < threshold) {
+            revert StaleOracleData(data.lastUpdatedBase, threshold);
+        }
+    }
+
+
+    // ──────────────────────────────────────────────────────────────────────
+    //  Generic getter — query any symbol the oracle supports
+    // ──────────────────────────────────────────────────────────────────────
+
+    /// @notice Returns the rate for an arbitrary base/USD pair scaled by 1e18.
+    function getPrice(string calldata _base) external view returns (uint256) {
+        return _getPrice(_base).rate;
+    }
+
+
+    /// @notice Returns the full ReferenceData for an arbitrary base/USD pair.
+    function getPriceData(string calldata _base) external view returns (IStdReference.ReferenceData memory) {
+        return _getPrice(_base);
+    }
+
+    /**
+     * @notice Updates the maximum staleness threshold.
+     * @param _maxStaleness New threshold in seconds (0 = disable check).
+     */
+    function setMaxStaleness(uint256 _maxStaleness) external onlyOwner {
+        if (_maxStaleness < MIN_STALENESS) revert StalenessTooLow(_maxStaleness, MIN_STALENESS);
+        emit MaxStalenessUpdated(maxStaleness, _maxStaleness);
+        maxStaleness = _maxStaleness;
+    }
+}

package/contracts/oracle/ICotiPriceConsumer.sol

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/**
+ * @title ICotiPriceConsumer
+ * @notice Minimal interface for the CotiPriceConsumer oracle used by the bridge
+ */
+interface ICotiPriceConsumer {
+   
+    /// @notice Returns the rate for an arbitrary base/USD pair scaled by 1e18.
+    function getPrice(string calldata _base) external view returns (uint256);
+
+    /// @notice Returns rate + metadata for any base/USD pair.
+    function getPriceWithMeta(string calldata _base) external view returns (uint256 rate, uint256 lastUpdated, uint256 blockTimestamp);
+}

package/contracts/oracle/IStdReference.sol

@@ -0,0 +1,26 @@
+// SPDX-License-Identifier: MIT
+pragma solidity ^0.8.20;
+
+/**
+ * @title IStdReference
+ * @notice Band Protocol Standard Reference interface for querying price data.
+ */
+interface IStdReference {
+    struct ReferenceData {
+        uint256 rate;            // base/quote exchange rate, scaled by 1e18
+        uint256 lastUpdatedBase; // UNIX epoch when the base price was last updated
+        uint256 lastUpdatedQuote; // UNIX epoch when the quote price was last updated
+    }
+
+    /// @notice Returns the price data for a single base/quote pair.
+    function getReferenceData(
+        string memory _base,
+        string memory _quote
+    ) external view returns (ReferenceData memory);
+
+    /// @notice Returns the price data for multiple base/quote pairs.
+    function getReferenceDataBulk(
+        string[] memory _bases,
+        string[] memory _quotes
+    ) external view returns (ReferenceData[] memory);
+}

package/contracts/pod/IInbox.sol

@@ -0,0 +1,231 @@
+// SPDX-License-Identifier: UNLICENSED
+pragma solidity ^0.8.20;
+
+/// @title IInbox
+/// @notice Cross-chain request/response inbox: send messages to remote chains, execute incoming calls, and query state.
+/// @dev Fee-related fields on {Request} are **gas unit** budgets, not wei. See {InboxFeeManager}.
+interface IInbox {
+    // --- Types ---
+
+    /// @notice Classification of the current inbox execution when delivering an error callback.
+    /// @dev Used by source `errorSelector` handlers: ignore {NotErrorContext}; branch on {SystemError} vs {Exception}.
+    ///      Call only from `errorSelector` entrypoints — linked success `respond` legs can also report {Exception}.
+    enum InboxErrorType {
+        /// @notice No active message, or the active call is not a linked error/system delivery.
+        NotErrorContext,
+        /// @notice Inbox system-error return leg (`originalSender` is {SYSTEM_SENDER}).
+        SystemError,
+        /// @notice Linked return leg for a request that registered an `errorSelector` (app `raise`).
+        Exception
+    }
+
+    /// @notice Minimal payload for Inbox system-error callbacks (`errorSelector(bytes data)`).
+    /// @dev App `raise` payloads are dApp-defined; decode them only when {inboxErrorType()} is {Exception}.
+    ///      System encode failure uses `errorCode = 2`. Attribution is via {SYSTEM_SENDER} on the return leg.
+    struct ErrorData {
+        uint64 errorCode;
+        bytes message;
+    }
+
+    /// @notice Encoded method call and optional MPC ABI metadata.
+    struct MpcMethodCall {
+        /// @notice Function selector to re-encode with MPC GTs; zero means `data` is raw calldata.
+        bytes4 selector;
+        /// @notice ABI-encoded arguments or raw calldata.
+        bytes data;
+        /// @notice MPC datatype descriptors used by {MpcAbiCodec}.
+        bytes8[] datatypes;
+        /// @notice MPC ciphertext length descriptors used by {MpcAbiCodec}.
+        bytes32[] datalens;
+    }
+
+    /// @notice Stored outbound or incoming cross-chain request.
+    struct Request {
+        /// @notice Packed request id containing source chain id and nonce.
+        bytes32 requestId;
+        /// @notice Destination chain id for outbound requests, or source chain id for incoming requests.
+        uint256 targetChainId;
+        /// @notice Contract invoked on the destination/current chain.
+        address targetContract;
+        /// @notice Method call executed on the target.
+        MpcMethodCall methodCall;
+        /// @notice Immediate caller that submitted the request.
+        address callerContract;
+        /// @notice Application contract that should receive responses/errors.
+        address originalSender;
+        /// @notice Request creation or ingestion timestamp.
+        uint64 timestamp;
+        /// @notice Callback selector used for two-way success responses.
+        bytes4 callbackSelector;
+        /// @notice Error selector invoked with `errorSelector(bytes data)` for app `raise` **or** Inbox system errors.
+        /// @dev Same delivery path. Distinguish with {inboxErrorType()}: {SystemError} ({ErrorData} payload,
+        ///      {SYSTEM_SENDER}) vs {Exception} (dApp-defined `raise` bytes). System errors are not eligible for
+        ///      `retryFailedRequest`. Auth: `onlyInbox` + non-zero {inboxSourceRequestId}.
+        bytes4 errorSelector;
+        /// @notice True when a success response is expected.
+        bool isTwoWay;
+        /// @notice True after an incoming request or linked response has been processed.
+        bool executed;
+        /// @dev If this request is a one-way response or error delivery, links to the original two-way request ID.
+        bytes32 sourceRequestId;
+        /// @dev Gas unit budget for the remote execution leg (`call{gas: ...}` cap). Not wei.
+        uint256 targetFee;
+        /// @dev Gas unit budget for the callback leg on the source chain. Not wei.
+        uint256 callerFee;
+    }
+
+    /// @notice Response metadata for an incoming request.
+    struct Response {
+        /// @notice Outbound request id that delivered the response.
+        bytes32 responseRequestId;
+        /// @notice Response payload returned by the target contract.
+        bytes response;
+    }
+
+    /// @notice Stored execution or encoding error for a request.
+    struct Error {
+        /// @notice Request id that failed.
+        bytes32 requestId;
+        /// @notice Protocol-defined error code.
+        uint64 errorCode;
+        /// @notice Revert data or encoded error message.
+        bytes errorMessage;
+    }
+
+    /// @notice Active incoming execution context exposed to target contracts.
+    struct ExecutionContext {
+        /// @notice Remote chain that sent the current request.
+        uint256 remoteChainId;
+        /// @notice Remote contract that sent the current request.
+        address remoteContract;
+        /// @notice Current incoming request id.
+        bytes32 requestId;
+    }
+
+    // --- External: sends (payable) ---
+
+    /// @notice Send a two-way message with callback and error handlers on the remote chain.
+    /// @param targetChainId Destination chain ID.
+    /// @param targetContract Contract to call on the destination chain.
+    /// @param methodCall Calldata and MPC metadata.
+    /// @param callbackSelector Selector invoked on the source chain when the remote call succeeds.
+    /// @param errorSelector Selector invoked on the source chain when the remote call fails.
+    /// @param callbackFeeLocalWei Wei from `msg.value` reserved for the callback leg (converted to gas units in fee logic).
+    /// @return requestId The new outbound request ID.
+    function sendTwoWayMessage(
+        uint256 targetChainId,
+        address targetContract,
+        MpcMethodCall calldata methodCall,
+        bytes4 callbackSelector,
+        bytes4 errorSelector,
+        uint256 callbackFeeLocalWei
+    ) external payable returns (bytes32);
+
+    /// @notice Send a one-way message with an error handler only (no callback).
+    /// @param targetChainId Destination chain ID.
+    /// @param targetContract Contract to call on the destination chain.
+    /// @param methodCall Calldata and MPC metadata.
+    /// @param errorSelector Selector invoked on error.
+    /// @return requestId The new outbound request ID.
+    function sendOneWayMessage(
+        uint256 targetChainId,
+        address targetContract,
+        MpcMethodCall calldata methodCall,
+        bytes4 errorSelector
+    ) external payable returns (bytes32);
+
+    // --- External: execution (non-payable) ---
+
+    /// @notice Respond to the current incoming message (two-way flow).
+    /// @dev Gas for the return leg is **not** charged again: it uses the `callerFee` budget from the original two-way request.
+    /// @param data Payload routed to the original sender via `callbackSelector`.
+    function respond(bytes memory data) external;
+
+    /// @notice Signal an application error for the current incoming two-way message (same routing constraints as {respond}).
+    /// @dev Gas for the return leg is **not** charged again: it uses the `callerFee` budget from the original two-way request.
+    /// @param data ABI-encoded argument for the remote `errorSelector(bytes)`.
+    function raise(bytes memory data) external;
+
+    // --- External: views ---
+
+    /// @notice Return error details for a failed outgoing request.
+    /// @param requestId Outbound request ID.
+    /// @return code Error code.
+    /// @return message Error message or revert data.
+    function getOutboxError(bytes32 requestId) external view returns (uint256 code, string memory message);
+
+    /// @notice Return stored response bytes for a completed incoming flow.
+    /// @param requestId Incoming request ID.
+    /// @return response Response payload.
+    function getInboxResponse(bytes32 requestId) external view returns (bytes memory);
+
+    /// @notice Return a slice of outbound requests sent to `targetChainId`, in per-target nonce order.
+    /// @param targetChainId Destination chain whose outbound requests to read.
+    /// @param from Start index (0-based) within that target's sequence.
+    /// @param len Maximum number of requests to return.
+    /// @return requestsList Request structs.
+    function getRequests(uint256 targetChainId, uint256 from, uint256 len)
+        external
+        view
+        returns (Request[] memory);
+
+    /// @notice Total count of outbound requests issued from this inbox to `targetChainId`.
+    /// @param targetChainId Destination chain.
+    /// @return count Number of requests to that target.
+    function getRequestsLen(uint256 targetChainId) external view returns (uint256);
+
+    /// @notice Look up a stored outbound request by its id (id encodes source+target+nonce).
+    /// @param requestId Outbound request id.
+    /// @return request The stored request (zeroed if unknown).
+    function getRequest(bytes32 requestId) external view returns (Request memory);
+
+    /// @notice Look up a stored incoming request by its id (id encodes the source chain).
+    /// @param requestId Incoming request id.
+    /// @return request The stored incoming request (zeroed if unknown).
+    function getIncomingRequest(bytes32 requestId) external view returns (Request memory);
+
+    /// @notice Remote chain ID and contract for the currently executing incoming message.
+    /// @dev For system-error return legs, `contractAddress` is {SYSTEM_SENDER}. Success callbacks still
+    ///      come from the real remote peer; error callbacks should not require peer equality.
+    /// @return chainId Remote chain ID.
+    /// @return contractAddress Remote caller contract (or {SYSTEM_SENDER} for Inbox system errors).
+    function inboxMsgSender() external view returns (uint256 chainId, address contractAddress);
+
+    /// @notice Request ID for the currently executing incoming message.
+    /// @return requestId Active request ID.
+    function inboxRequestId() external view returns (bytes32);
+
+    /// @notice Source request ID linked from the current incoming message (if any).
+    /// @dev Non-zero only for reply/error legs created by {respond}, {raise}, or system-error delivery.
+    ///      Public {sendOneWayMessage}/{sendTwoWayMessage} always use `sourceRequestId = 0`.
+    /// @return sourceRequestId Linked request ID.
+    function inboxSourceRequestId() external view returns (bytes32);
+
+    /// @notice Whether the current execution is delivering a system error, an app `raise`, or neither.
+    /// @dev Safe to call outside an active message (returns {InboxErrorType.NotErrorContext}). Prefer this over
+    ///      requiring `inboxMsgSender()` peer equality in error handlers.
+    /// @return errorType {InboxErrorType} for the active context.
+    function inboxErrorType() external view returns (InboxErrorType errorType);
+
+    // --- External: pure ---
+
+    /// @notice Pack source chain id (64 bits), target chain id (64 bits) and nonce (128 bits) into a request id.
+    /// @param sourceChainId Originating chain id.
+    /// @param targetChainId Destination chain id.
+    /// @param nonce Per-target nonce.
+    /// @return requestId 256-bit packed id.
+    function getRequestId(uint256 sourceChainId, uint256 targetChainId, uint256 nonce)
+        external
+        pure
+        returns (bytes32);
+
+    /// @notice Split a packed request id into source chain id, target chain id and nonce.
+    /// @param requestId Packed id.
+    /// @return sourceChainId Source chain id.
+    /// @return targetChainId Target chain id.
+    /// @return nonce Per-target nonce.
+    function unpackRequestId(bytes32 requestId)
+        external
+        pure
+        returns (uint256 sourceChainId, uint256 targetChainId, uint256 nonce);
+}