expand on use of callWithTrieNodes

contracts/Challenge.sol

@@ -84,7 +84,8 @@ contract Challenge {
   ///         Before calling this, it is necessary to have loaded all the trie node necessary to
   ///         write the input hash in the Merkleized initial MIPS state, and to read the output hash
   ///         and machine state from the Merkleized final MIPS state (i.e. `finalSystemState`). Use
-  ///         `MIPSMemory.AddTrieNode` for this purpose.
+  ///         `MIPSMemory.AddTrieNode` for this purpose. Use `callWithTrieNodes` to figure out
+  ///         which nodes you need.
   /// @param blockNumberN The number N of the parent of the block being challenged
   /// @param blockHeaderNp1 The RLP-encoded header of the block being challenged (N+1)
   /// @param assertionRoot The state root that the challenger claims is the correct one for the
@@ -162,16 +163,15 @@ contract Challenge {
     return challengeId;
   }
 
-  /// @notice Calling `initiateChallenge` requires some trie nodes to have been supplied beforehand,
-  ///         in order to be able to write the input hash in the Merkleized initial MIPS state, and
-  ///         to read the output hash and machine state from the Merkleized final MIPS state.
-  ///         This function can be used to figure out which nodes are needed, as memory-reading
+  /// @notice Calling `initiateChallenge`, `confirmStateTransition` or `denyStateTransition requires
+  ///         some trie nodes to have been supplied beforehand (see these functions for details).
+  ///         This function can be used to figure out which nodes are needed, as memory-accessing
   ///         functions in MIPSMemory.sol will revert with the missing node ID when a node is
   ///         missing. Therefore, you can call this function repeatedly via `eth_call`, and
   ///         iteratively build the list of required node until the call succeeds.
   /// @param target The contract to call to (usually this contract)
   /// @param dat The data to include in the call (usually the calldata for a call to
-  ///        `initiateChallenge`
+  ///        one of the aforementionned functions)
   /// @param nodes The nodes to add the MIPS state trie before making the call
   function callWithTrieNodes(address target, bytes calldata dat, bytes[] calldata nodes) public {
     for (uint i = 0; i < nodes.length; i++) {
@@ -266,6 +266,9 @@ contract Challenge {
   /// @notice Anybody can call this function to confirm that the single execution step that the
   ///         challenger and defender disagree on does indeed yield the result asserted by the
   ///         challenger, leading to him winning the challenge.
+  ///         Before calling this function, you need to add trie nodes so that the MIPS state can be
+  ///         read/written by the single step execution. Use `MIPSMemory.AddTrieNode` for this
+  ///         purpose. Use `callWithTrieNodes` to figure out which nodes you need.
   function confirmStateTransition(uint256 challengeId) external {
     ChallengeData storage c = challenges[challengeId];
     require(c.challenger != address(0), "invalid challenge");
@@ -284,6 +287,9 @@ contract Challenge {
   /// @notice Anybody can call this function to confirm that the single execution step that the
   ///         challenger and defender disagree on does indeed yield the result asserted by the
   ///         defender, leading to the challenger losing the challenge.
+  ///         Before calling this function, you need to add trie nodes so that the MIPS state can be
+  ///         read/written by the single step execution. Use `MIPSMemory.AddTrieNode` for this
+  ///         purpose. Use `callWithTrieNodes` to figure out which nodes you need.
   function denyStateTransition(uint256 challengeId) external {
     ChallengeData storage c = challenges[challengeId];
     require(c.challenger != address(0), "invalid challenge");