From 96fae0c2201caf33b134e40d770927ee60074fe6 Mon Sep 17 00:00:00 2001
From: Chris Ward <chris.ward@ethereum.org>
Date: Sun, 20 Jan 2019 19:32:59 +0200
Subject: Move FAQ item about truncation checks

Move warning

Updates from feedback

Link to security note and fix link rendering

Move solution to security docs and turn warning to a warning
---
 docs/frequently-asked-questions.rst | 13 -------------
 docs/security-considerations.rst    |  6 ++++--
 docs/types/value-types.rst          |  5 +++++
 3 files changed, 9 insertions(+), 15 deletions(-)

diff --git a/docs/frequently-asked-questions.rst b/docs/frequently-asked-questions.rst
index 645789ce..00d9e043 100644
--- a/docs/frequently-asked-questions.rst
+++ b/docs/frequently-asked-questions.rst
@@ -89,19 +89,6 @@ In this example::
         }
     }
 
-What does the following strange check do in the Custom Token contract?
-======================================================================
-
-::
-
-    require((balanceOf[_to] + _value) >= balanceOf[_to]);
-
-Integers in Solidity (and most other machine-related programming languages) are restricted to a certain range.
-For ``uint256``, this is ``0`` up to ``2**256 - 1``. If the result of some operation on those numbers
-does not fit inside this range, it is truncated. These truncations can have
-`serious consequences <https://en.bitcoin.it/wiki/Value_overflow_incident>`_, so code like the one
-above is necessary to avoid certain attacks.
-
 More Questions?
 ===============
 
diff --git a/docs/security-considerations.rst b/docs/security-considerations.rst
index d83302a0..ebc39ad0 100644
--- a/docs/security-considerations.rst
+++ b/docs/security-considerations.rst
@@ -223,7 +223,7 @@ Now someone tricks you into sending ether to the address of this attack wallet:
 
 If your wallet had checked ``msg.sender`` for authorization, it would get the address of the attack wallet, instead of the owner address. But by checking ``tx.origin``, it gets the original address that kicked off the transaction, which is still the owner address. The attack wallet instantly drains all your funds.
 
-
+.. _underflow-overflow:
 
 Two's Complement / Underflows / Overflows
 =========================================
@@ -241,9 +241,11 @@ more special edge cases for signed numbers.
 Try to use ``require`` to limit the size of inputs to a reasonable range and use the
 :ref:`SMT checker<smt_checker>` to find potential overflows, or
 use a library like
-`SafeMath<https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/math/SafeMath.sol>`
+`SafeMath <https://github.com/OpenZeppelin/openzeppelin-solidity/blob/master/contracts/math/SafeMath.sol>`_
 if you want all overflows to cause a revert.
 
+Code such as ``require((balanceOf[_to] + _value) >= balanceOf[_to])`` can also help you check if values are what you expect.
+
 Minor Details
 =============
 
diff --git a/docs/types/value-types.rst b/docs/types/value-types.rst
index 09db1423..b85863dd 100644
--- a/docs/types/value-types.rst
+++ b/docs/types/value-types.rst
@@ -39,6 +39,11 @@ Operators:
 * Shift operators: ``<<`` (left shift), ``>>`` (right shift)
 * Arithmetic operators: ``+``, ``-``, unary ``-``, ``*``, ``/``, ``%`` (modulo), ``**`` (exponentiation)
 
+.. warning::
+
+  Integers in Solidity are restricted to a certain range. For example, with ``uint32``, this is ``0`` up to ``2**32 - 1``.
+  If the result of some operation on those numbers does not fit inside this range, it is truncated. These truncations can have
+  serious consequences that you should :ref:`be aware of and mitigate against<underflow-overflow>`.
 
 Comparisons
 ^^^^^^^^^^^
-- 
cgit