:broom: docs

packages/contracts-bedrock/contracts/libraries/SafeCall.sol

@@ -57,9 +57,10 @@ library SafeCall {
             //
             // Because EIP-150 ensures that, at max, 64/64ths of the remaining gas in the call
             // frame may be passed to a subcontext, we need to ensure that the gas will not be
-            // truncated to hold the invariant. In addition, exactly 51 gas is consumed between
-            // the below `GAS` opcode and the `CALL` opcode, so it is factored in with some extra
-            // room for error.
+            // truncated to hold this function's invariant: "If a call is performed by
+            // `callWithMinGas`, it must receive at least the specified minimum gas limit." In
+            // addition, exactly 51 gas is consumed between the below `GAS` opcode and the `CALL`
+            // opcode, so it is factored in with some extra room for error.
             if lt(gas(), div(shl(0x06, add(_minGas, 0xC8)), 0x3F)) {
                 // Store the "Error(string)" selector in scratch space.
                 mstore(0x00, 0x08c379a0)

packages/contracts-bedrock/contracts/test/invariants/SafeCall.t.sol

@@ -21,11 +21,11 @@ contract SafeCall_Succeeds_Invariants is Test {
     }
 
     /**
-     * @custom:invariant `callWithMinGas` forwards at least `minGas` if the call succeeds.
+     * @custom:invariant If `callWithMinGas` performs a call, then it must always
+     * provide at least the specified minimum gas limit to the subcontext.
      *
-     * If the call to `SafeCall.callWithMinGas` succeeds, then the
-     * call must have received at *least* `minGas` gas. If there is not enough gas in
-     * the callframe to supply the minimum amount of gas to the call, it must revert.
+     * If the check for remaining gas in `SafeCall.callWithMinGas` passes, the
+     * subcontext of the call below it must be provided at least `minGas` gas.
      */
     function invariant_callWithMinGas_alwaysForwardsMinGas_succeeds() public {
         assertEq(actor.numFailed(), 0, "no failed calls allowed");
@@ -52,11 +52,11 @@ contract SafeCall_Fails_Invariants is Test {
 
     /**
      * @custom:invariant `callWithMinGas` reverts if there is not enough gas to pass
-     * to the call.
+     * to the subcontext.
      *
-     * If there is not enough gas in the callframe to ensure that
-     * `SafeCall.callWithMinGas` will receive at least `minGas` gas, then the call
-     * must revert.
+     * If there is not enough gas in the callframe to ensure that `callWithMinGas`
+     * can provide the specified minimum gas limit to the subcontext of the call,
+     * then `callWithMinGas` must revert.
      */
     function invariant_callWithMinGas_neverForwardsMinGas_reverts() public {
         assertEq(actor.numSuccessful(), 0, "no successful calls allowed");

packages/contracts-bedrock/invariant-docs/SafeCall.md

 # `SafeCall` Invariants
 
-## `callWithMinGas` forwards at least `minGas` if the call succeeds.
+## If `callWithMinGas` performs a call, then it must always provide at least the specified minimum gas limit to the subcontext.
 **Test:** [`SafeCall.t.sol#L30`](../contracts/test/invariants/SafeCall.t.sol#L30)
 
-If the call to `SafeCall.callWithMinGas` succeeds, then the call must have received at *least* `minGas` gas. If there is not enough gas in the callframe to supply the minimum amount of gas to the call, it must revert. 
+If the check for remaining gas in `SafeCall.callWithMinGas` passes, the subcontext of the call below it must be provided at least `minGas` gas. 
 
 
-## `callWithMinGas` reverts if there is not enough gas to pass to the call.
+## `callWithMinGas` reverts if there is not enough gas to pass to the subcontext.
 **Test:** [`SafeCall.t.sol#L61`](../contracts/test/invariants/SafeCall.t.sol#L61)
 
-If there is not enough gas in the callframe to ensure that `SafeCall.callWithMinGas` will receive at least `minGas` gas, then the call must revert. 
+If there is not enough gas in the callframe to ensure that `callWithMinGas` can provide the specified minimum gas limit to the subcontext of the call, then `callWithMinGas` must revert.