docs

src/Orders.sol

@@ -61,6 +61,7 @@ abstract contract OrderDestination is OutputPermit2 {
     /// @dev Filler may aggregate multiple Outputs with the same (`chainId`, `recipient`, `token`) into a single Output with the summed `amount`.
     /// @dev the permit2 signer is the Filler providing the Outputs.
     /// @dev the permit2 `permitted` tokens MUST match provided Outputs.
+    /// @dev Filler MUST submit `fill` and `intitiate` within an atomic bundle.
     /// @dev NOTE that here, Output.chainId denotes the *origin* chainId.
     /// @param outputs - The Outputs to be transferred. signed over via permit2 witness.
     /// @param permit2 - the permit2 details, signer, and signature.
@@ -91,14 +92,15 @@ abstract contract OrderOrigin is OutputPermit2 {
     ///      Intentionally does not bother to emit which token(s) were swept, nor their amounts.
     event Sweep(address indexed recipient, address indexed token, uint256 amount);
 
-    /// @notice Request to swap ERC20s.
+    /// @notice Initiate an Order.
+    /// @dev Filler MUST submit `fill` and `intitiate` + `sweep` within an atomic bundle.
+    /// @dev NOTE that here, Output.chainId denotes the *target* chainId.
     /// @dev inputs are provided on the rollup; in exchange,
     ///      outputs are expected to be received on the target chain(s).
-    /// @dev Fees paid to the Builders for fulfilling the Orders
-    ///      can be included within the "exchange rate" between inputs and outputs.
-    /// @dev The Builder claims the inputs from the contract by submitting `sweep` transactions within the same block.
     /// @dev The Rollup STF MUST NOT apply `initiate` transactions to the rollup state
     ///      UNLESS the outputs are delivered on the target chains within the same block.
+    /// @dev Fees paid to the Builders for fulfilling the Orders
+    ///      can be included within the "exchange rate" between inputs and outputs.
     /// @param deadline - The deadline at or before which the Order must be fulfilled.
     /// @param inputs - The token amounts offered by the swapper in exchange for the outputs.
     /// @param outputs - The token amounts that must be received on their target chain(s) in order for the Order to be executed.
@@ -128,18 +130,15 @@ abstract contract OrderOrigin is OutputPermit2 {
         }
     }
 
-    /// @notice Initiate an Order, transferring Input tokens via permit2 signed batch transfer.
+    /// @notice Initiate an Order, transferring Input tokens to the Filler via permit2 signed batch transfer.
     /// @dev Can only provide ERC20 tokens as Inputs.
     /// @dev the permit2 signer is the swapper providing the Input tokens in exchange for the Outputs.
-    /// @dev MUST submit `fill` and `intitiate` within an atomic bundle.
+    /// @dev Filler MUST submit `fill` and `intitiate` within an atomic bundle.
+    /// @dev NOTE that here, Output.chainId denotes the *target* chainId.
     /// @param tokenRecipient - the recipient of the Input tokens, provided by msg.sender (un-verified by permit2).
     /// @param outputs - the Outputs required in exchange for the Input tokens. signed over via permit2 witness.
     /// @param permit2 - the permit2 details, signer, and signature.
-    function initiatePermit2(
-        address tokenRecipient, /* unsigned */
-        Output[] memory outputs, /* signed via permit2 witness */
-        Permit2 calldata permit2
-    ) external {
+    function initiatePermit2(address tokenRecipient, Output[] memory outputs, Permit2 calldata permit2) external {
         _permitWitnessTransferFrom(outputs, _initiateTransferDetails(tokenRecipient, permit2.permit.permitted), permit2);
 
         // emit

src/UsesPermit2.sol

@@ -88,9 +88,9 @@ abstract contract OutputPermit2 {
         }
     }
 
-    /// @notice transform TokenPermissions structs to Inputs structs, for emitting.
-    /// @dev TokenPermissions and Inputs structs contain identical fields.
     /// @param permitted - the TokenPermissions to transform.
+    /// @notice transform permit2 TokenPermissions to Inputs structs, for emitting.
+    /// @dev TokenPermissions and Inputs structs contain identical fields - (address token, uint256 amount).
     /// @return inputs - the Inputs generated.
     function _inputs(ISignatureTransfer.TokenPermissions[] calldata permitted)
         internal