✨ Add checkBalanceOf and regen docs (#1397)

Author: Vectorized

docs/utils/p256.md

@@ -28,7 +28,7 @@ facilitate easier existence check. This verifier will also never revert.
 
 ```solidity
 address internal constant CANARY =
-    0x0000000000009D47E8d483936dc4B6b4bf7bbFe6
+    0x0000000000001Ab2e8006Fd8B71907bf06a5BDEE
 ```
 
 The existence of this contract, as determined by non-empty bytecode,   

docs/utils/safetransferlib.md

@@ -319,6 +319,19 @@ function balanceOf(address token, address account)
 Returns the amount of ERC20 `token` owned by `account`.   
 Returns zero if the `token` does not exist.
 
+### checkBalanceOf(address,address)
+
+```solidity
+function checkBalanceOf(address token, address account)
+    internal
+    view
+    returns (bool implemented, uint256 amount)
+```
+
+Performs a `token.balanceOf(account)` check.   
+`implemented` denotes whether the `token` does not implement `balanceOf`.   
+`amount` is zero if the `token` does not implement `balanceOf`.
+
 ### totalSupply(address)
 
 ```solidity

src/utils/SafeTransferLib.sol

@@ -405,6 +405,27 @@ library SafeTransferLib {
         }
     }
 
+    /// @dev Performs a `token.balanceOf(account)` check.
+    /// `implemented` denotes whether the `token` does not implement `balanceOf`.
+    /// `amount` is zero if the `token` does not implement `balanceOf`.
+    function checkBalanceOf(address token, address account)
+        internal
+        view
+        returns (bool implemented, uint256 amount)
+    {
+        /// @solidity memory-safe-assembly
+        assembly {
+            mstore(0x14, account) // Store the `account` argument.
+            mstore(0x00, 0x70a08231000000000000000000000000) // `balanceOf(address)`.
+            implemented :=
+                and( // The arguments of `and` are evaluated from right to left.
+                    gt(returndatasize(), 0x1f), // At least 32 bytes returned.
+                    staticcall(gas(), token, 0x10, 0x24, 0x20, 0x20)
+                )
+            amount := mul(mload(0x20), implemented)
+        }
+    }
+
     /// @dev Returns the total supply of the `token`.
     /// Reverts if the token does not exist or does not implement `totalSupply()`.
     function totalSupply(address token) internal view returns (uint256 result) {

test/SafeTransferLib.t.sol

@@ -386,6 +386,23 @@ contract SafeTransferLibTest is SoladyTest {
         assertEq(SafeTransferLib.balanceOf(address(erc20), _brutalized(address(this))), amount);
     }
 
+    function testCheckBalanceOfNonImplemented() public {
+        (bool implemented,) = SafeTransferLib.checkBalanceOf(address(0), _brutalized(address(this)));
+        assertFalse(implemented);
+    }
+
+    function testCheckBalanceOf(address to, uint256 amount) public {
+        uint256 originalBalance = erc20.balanceOf(address(this));
+        while (originalBalance < amount) amount = _random();
+        while (to == address(this)) to = _randomHashedAddress();
+
+        SafeTransferLib.safeTransfer(address(erc20), _brutalized(to), originalBalance - amount);
+        (bool implemented, uint256 retrievedAmount) =
+            SafeTransferLib.checkBalanceOf(address(erc20), _brutalized(address(this)));
+        assertEq(retrievedAmount, amount);
+        assertTrue(implemented);
+    }
+
     function testTransferAllWithStandardERC20() public {
         SafeTransferLib.safeTransferAll(address(erc20), address(1));
     }