Merge pull request #231 from oasisprotocol/CU-86934gu0x_Add-security-…

…notice-for-block-checking_Xi-Zhang

Add Security documentation to ensure finality

docs/security.md

@@ -76,6 +76,38 @@ function transferFrom(address who, address to, uint amount)
 }
 ```
 
+## Speed Bump
+
+If we would like to prevent off-chain calls from being chained together, we can
+ensure that the block has been finalized.
+
+```solidity
+contract Secret {
+  uint256 private _height;
+  bytes private _secret;
+  address private _buyer;
+
+  constructor(bytes memory _text) {
+    _secret = _text;
+  }
+
+  function recordPayment() external payable {
+    require(msg.value == 1 ether);
+    // set and lock buyer
+    _height = block.number;
+    _buyer = msg.sender;
+  }
+
+  /// @notice Reveals the secret.
+  function revealSecret() view external returns (bytes memory) {
+    require(block.number > _height, "not settled");
+    require(_buyer != address(0), "no recorded buyer");
+    // TODO: optionally authenticate call from buyer
+    return _secret;
+  }
+}
+```
+
 ## Gas Padding
 
 To prevent leaking information about a particular transaction, Sapphire