Merge pull request rainlanguage#8 from rainprotocol/2023-09-14-docs

docs

.gas-snapshot

@@ -0,0 +1 @@
+IFlowV4Test:testSentinelValue() (gas: 332)

src/concrete/basic/Flow.sol

@@ -8,17 +8,33 @@ import {
     LibContext,
     MIN_FLOW_SENTINELS
 } from "../../abstract/FlowCommon.sol";
-import {IFlowV4, Evaluable, FlowTransferV1, SignedContextV1, EvaluableConfigV2, LibFlow} from "../../lib/LibFlow.sol";
+import {IFlowV4, LibFlow} from "../../lib/LibFlow.sol";
 import {LibUint256Matrix} from "rain.solmem/lib/LibUint256Matrix.sol";
 import {Pointer} from "rain.solmem/lib/LibPointer.sol";
+import {LibUint256Array} from "rain.solmem/lib/LibUint256Array.sol";
+import {Evaluable, EvaluableConfigV2} from "rain.interpreter/src/lib/caller/LibEvaluable.sol";
+import {FlowTransferV1} from "../../interface/unstable/IFlowV4.sol";
+import {SignedContextV1} from "rain.interpreter/src/interface/IInterpreterCallerV2.sol";
 
+/// @dev The hash of the meta data expected to be passed to `FlowCommon`'s
+/// constructor.
 bytes32 constant CALLER_META_HASH = bytes32(0x95de68a447a477b8fab10701f1265b3e85a98b24710b3e40e6a96aa6d76263bc);
 
+/// @title Flow
+/// See `IFlowV4` docs.
 contract Flow is ICloneableV2, IFlowV4, FlowCommon {
     using LibUint256Matrix for uint256[];
+    using LibUint256Array for uint256[];
 
+    /// Forwards to `FlowCommon` constructor.
     constructor(DeployerDiscoverableMetaV2ConstructionConfig memory config) FlowCommon(CALLER_META_HASH, config) {}
 
+    /// Overloaded typed initialize function MUST revert with this error.
+    /// As per `ICloneableV2` interface.
+    function initialize(EvaluableConfigV2[] memory) external pure {
+        revert InitializeSignatureFn();
+    }
+
     /// @inheritdoc ICloneableV2
     function initialize(bytes calldata data) external initializer returns (bytes32) {
         EvaluableConfigV2[] memory flowConfig = abi.decode(data, (EvaluableConfigV2[]));
@@ -28,25 +44,12 @@ contract Flow is ICloneableV2, IFlowV4, FlowCommon {
         return ICLONEABLE_V2_SUCCESS;
     }
 
-    function _previewFlow(Evaluable memory evaluable, uint256[][] memory context)
-        internal
-        view
-        returns (FlowTransferV1 memory, uint256[] memory)
-    {
-        (Pointer stackBottom, Pointer stackTop, uint256[] memory kvs) = flowStack(evaluable, context);
-        return (LibFlow.stackToFlow(stackBottom, stackTop), kvs);
-    }
-
-    function previewFlow(
-        Evaluable memory evaluable,
-        uint256[] memory callerContext,
-        SignedContextV1[] memory signedContexts
-    ) external view virtual returns (FlowTransferV1 memory) {
-        uint256[][] memory context = LibContext.build(callerContext.matrixFrom(), signedContexts);
-        (FlowTransferV1 memory flowTransfer,) = _previewFlow(evaluable, context);
-        return flowTransfer;
+    /// @inheritdoc IFlowV4
+    function stackToFlow(uint256[] memory stack) external pure virtual override returns (FlowTransferV1 memory) {
+        return LibFlow.stackToFlow(stack.dataPointer(), stack.endPointer());
     }
 
+    /// @inheritdoc IFlowV4
     function flow(Evaluable memory evaluable, uint256[] memory callerContext, SignedContextV1[] memory signedContexts)
         external
         virtual
@@ -55,7 +58,8 @@ contract Flow is ICloneableV2, IFlowV4, FlowCommon {
     {
         uint256[][] memory context = LibContext.build(callerContext.matrixFrom(), signedContexts);
         emit Context(msg.sender, context);
-        (FlowTransferV1 memory flowTransfer, uint256[] memory kvs) = _previewFlow(evaluable, context);
+        (Pointer stackBottom, Pointer stackTop, uint256[] memory kvs) = flowStack(evaluable, context);
+        FlowTransferV1 memory flowTransfer = LibFlow.stackToFlow(stackBottom, stackTop);
         LibFlow.flow(flowTransfer, evaluable.store, kvs);
         return flowTransfer;
     }

src/concrete/erc1155/FlowERC1155.sol

@@ -14,14 +14,15 @@ import {
     FlowERC1155IOV1,
     SignedContextV1,
     FlowERC1155ConfigV2,
-    ERC1155SupplyChange
+    ERC1155SupplyChange,
+    RAIN_FLOW_ERC1155_SENTINEL
 } from "../../interface/unstable/IFlowERC1155V4.sol";
 import {LibBytecode} from "lib/rain.interpreter/src/lib/bytecode/LibBytecode.sol";
 import {IInterpreterV1} from "rain.interpreter/src/interface/IInterpreterV1.sol";
 import {IInterpreterStoreV1} from "rain.interpreter/src/interface/IInterpreterStoreV1.sol";
 import {Evaluable, DEFAULT_STATE_NAMESPACE} from "rain.interpreter/src/lib/caller/LibEvaluable.sol";
 import {Pointer} from "rain.solmem/lib/LibPointer.sol";
-import {SENTINEL_HIGH_BITS, LibFlow} from "../../lib/LibFlow.sol";
+import {LibFlow} from "../../lib/LibFlow.sol";
 import {SourceIndex} from "rain.interpreter/src/interface/IInterpreterV1.sol";
 import {
     MIN_FLOW_SENTINELS,
@@ -31,9 +32,6 @@ import {
 } from "../../abstract/FlowCommon.sol";
 import {LibContext} from "rain.interpreter/src/lib/caller/LibContext.sol";
 
-Sentinel constant RAIN_FLOW_ERC1155_SENTINEL =
-    Sentinel.wrap(uint256(keccak256(bytes("RAIN_FLOW_ERC1155_SENTINEL")) | SENTINEL_HIGH_BITS));
-
 bytes32 constant CALLER_META_HASH = bytes32(0x7ea70f837234357ec1bb5b777e04453ebaf3ca778a98805c4bb20a738d559a21);
 
 SourceIndex constant HANDLE_TRANSFER_ENTRYPOINT = SourceIndex.wrap(0);
@@ -51,6 +49,12 @@ contract FlowERC1155 is ICloneableV2, IFlowERC1155V4, FlowCommon, ERC1155 {
 
     constructor(DeployerDiscoverableMetaV2ConstructionConfig memory config) FlowCommon(CALLER_META_HASH, config) {}
 
+    /// Overloaded typed initialize function MUST revert with this error.
+    /// As per `ICloneableV2` interface.
+    function initialize(FlowERC1155ConfigV2 memory) external pure {
+        revert InitializeSignatureFn();
+    }
+
     /// @inheritdoc ICloneableV2
     function initialize(bytes calldata data) external initializer returns (bytes32) {
         FlowERC1155ConfigV2 memory flowERC1155Config = abi.decode(data, (FlowERC1155ConfigV2));

src/concrete/erc20/FlowERC20.sol

@@ -15,9 +15,9 @@ import {
 } from "../../interface/unstable/IFlowERC20V4.sol";
 import {LibBytecode} from "lib/rain.interpreter/src/lib/bytecode/LibBytecode.sol";
 import {EncodedDispatch, LibEncodedDispatch} from "rain.interpreter/src/lib/caller/LibEncodedDispatch.sol";
-
+import {RAIN_FLOW_ERC20_SENTINEL} from "../../interface/unstable/IFlowERC20V4.sol";
 import {Sentinel, LibStackSentinel} from "rain.solmem/lib/LibStackSentinel.sol";
-import {SENTINEL_HIGH_BITS, LibFlow} from "../../lib/LibFlow.sol";
+import {LibFlow} from "../../lib/LibFlow.sol";
 import {
     FlowCommon,
     DeployerDiscoverableMetaV2,
@@ -32,23 +32,34 @@ import {LibContext} from "rain.interpreter/src/lib/caller/LibContext.sol";
 
 bytes32 constant CALLER_META_HASH = bytes32(0xff0499e4ee7171a54d176cfe13165a7ea512d146dbd99d42b3d3ec9963025acf);
 
-Sentinel constant RAIN_FLOW_ERC20_SENTINEL =
-    Sentinel.wrap(uint256(keccak256(bytes("RAIN_FLOW_ERC20_SENTINEL")) | SENTINEL_HIGH_BITS));
-
 SourceIndex constant HANDLE_TRANSFER_ENTRYPOINT = SourceIndex.wrap(0);
 uint256 constant HANDLE_TRANSFER_MIN_OUTPUTS = 0;
 uint16 constant HANDLE_TRANSFER_MAX_OUTPUTS = 0;
 
 /// @title FlowERC20
+/// See `IFlowERC20V4` for documentation.
 contract FlowERC20 is ICloneableV2, IFlowERC20V4, FlowCommon, ERC20 {
     using LibStackSentinel for Pointer;
     using LibUint256Matrix for uint256[];
 
+    /// @dev True if we need to eval `handleTransfer` on every transfer. For many
+    /// tokens this will be false, so we don't want to invoke the external
+    /// interpreter call just to cause a noop.
     bool private sEvalHandleTransfer;
+
+    /// @dev The evaluable that will be used to evaluate `handleTransfer` on
+    /// every transfer. This is only set if `sEvalHandleTransfer` is true.
     Evaluable internal sEvaluable;
 
+    /// Forwards the `FlowCommon` constructor arguments to the `FlowCommon`
     constructor(DeployerDiscoverableMetaV2ConstructionConfig memory config) FlowCommon(CALLER_META_HASH, config) {}
 
+    /// Overloaded typed initialize function MUST revert with this error.
+    /// As per `ICloneableV2` interface.
+    function initialize(FlowERC20ConfigV2 memory) external pure {
+        revert InitializeSignatureFn();
+    }
+
     /// @inheritdoc ICloneableV2
     function initialize(bytes calldata data) external initializer returns (bytes32) {
         FlowERC20ConfigV2 memory flowERC20Config = abi.decode(data, (FlowERC20ConfigV2));

src/concrete/erc721/FlowERC721.sol

@@ -18,7 +18,7 @@ import {
 } from "../../interface/unstable/IFlowERC721V4.sol";
 import {LibBytecode} from "lib/rain.interpreter/src/lib/bytecode/LibBytecode.sol";
 import {SourceIndex} from "rain.interpreter/src/interface/IInterpreterV1.sol";
-import {LibFlow, SENTINEL_HIGH_BITS} from "../../lib/LibFlow.sol";
+import {LibFlow} from "../../lib/LibFlow.sol";
 import {
     FlowCommon,
     DeployerDiscoverableMetaV2ConstructionConfig,
@@ -30,13 +30,11 @@ import {Evaluable, DEFAULT_STATE_NAMESPACE} from "rain.interpreter/src/lib/calle
 import {IInterpreterV1} from "rain.interpreter/src/interface/IInterpreterV1.sol";
 import {IInterpreterStoreV1} from "rain.interpreter/src/interface/IInterpreterStoreV1.sol";
 import {Pointer} from "rain.solmem/lib/LibPointer.sol";
+import {RAIN_FLOW_ERC721_SENTINEL} from "../../interface/unstable/IFlowERC721V4.sol";
 
 /// Thrown when burner of tokens is not the owner of tokens.
 error BurnerNotOwner();
 
-Sentinel constant RAIN_FLOW_ERC721_SENTINEL =
-    Sentinel.wrap(uint256(keccak256(bytes("RAIN_FLOW_ERC721_SENTINEL")) | SENTINEL_HIGH_BITS));
-
 bytes32 constant CALLER_META_HASH = bytes32(0x7f7944a4b89741668c06a27ffde94e19be970cd0506786de91aee01c2893d4ef);
 
 SourceIndex constant HANDLE_TRANSFER_ENTRYPOINT = SourceIndex.wrap(0);
@@ -58,6 +56,12 @@ contract FlowERC721 is ICloneableV2, IFlowERC721V4, FlowCommon, ERC721 {
 
     constructor(DeployerDiscoverableMetaV2ConstructionConfig memory config) FlowCommon(CALLER_META_HASH, config) {}
 
+    /// Overloaded typed initialize function MUST revert with this error.
+    /// As per `ICloneableV2` interface.
+    function initialize(FlowERC721ConfigV2 memory) external pure {
+        revert InitializeSignatureFn();
+    }
+
     /// @inheritdoc ICloneableV2
     function initialize(bytes calldata data) external initializer returns (bytes32) {
         FlowERC721ConfigV2 memory flowERC721Config = abi.decode(data, (FlowERC721ConfigV2));

src/interface/unstable/IFlowERC1155V4.sol

@@ -3,9 +3,14 @@ pragma solidity ^0.8.18;
 
 import {SignedContextV1} from "rain.interpreter/src/interface/IInterpreterCallerV2.sol";
 import {Evaluable, EvaluableConfigV2} from "rain.interpreter/src/lib/caller/LibEvaluable.sol";
+import {Sentinel} from "rain.solmem/lib/LibStackSentinel.sol";
+import {SENTINEL_HIGH_BITS} from "./IFlowV4.sol";
 
 import {FlowERC1155IOV1, ERC1155SupplyChange} from "../IFlowERC1155V3.sol";
 
+Sentinel constant RAIN_FLOW_ERC1155_SENTINEL =
+    Sentinel.wrap(uint256(keccak256(bytes("RAIN_FLOW_ERC1155_SENTINEL")) | SENTINEL_HIGH_BITS));
+
 struct FlowERC1155ConfigV2 {
     string uri;
     EvaluableConfigV2 evaluableConfig;

src/interface/unstable/IFlowERC20V4.sol

@@ -3,8 +3,12 @@ pragma solidity ^0.8.18;
 
 import {SignedContextV1} from "rain.interpreter/src/interface/IInterpreterCallerV2.sol";
 import {Evaluable, EvaluableConfigV2} from "rain.interpreter/src/lib/caller/LibEvaluable.sol";
-
+import {Sentinel} from "rain.solmem/lib/LibStackSentinel.sol";
 import {FlowERC20IOV1, ERC20SupplyChange} from "../IFlowERC20V3.sol";
+import {SENTINEL_HIGH_BITS} from "./IFlowV4.sol";
+
+Sentinel constant RAIN_FLOW_ERC20_SENTINEL =
+    Sentinel.wrap(uint256(keccak256(bytes("RAIN_FLOW_ERC20_SENTINEL")) | SENTINEL_HIGH_BITS));
 
 /// Constructor config.
 /// @param name As per Open Zeppelin `ERC20Upgradeable`.

src/interface/unstable/IFlowERC721V4.sol

@@ -8,6 +8,9 @@ import {FlowERC721IOV1, ERC721SupplyChange} from "../IFlowERC721V3.sol";
 
 import "./IFlowV4.sol";
 
+Sentinel constant RAIN_FLOW_ERC721_SENTINEL =
+    Sentinel.wrap(uint256(keccak256(bytes("RAIN_FLOW_ERC721_SENTINEL")) | SENTINEL_HIGH_BITS));
+
 /// Constructor config.
 /// @param name As per Open Zeppelin `ERC721Upgradeable`.
 /// @param symbol As per Open Zeppelin `ERC721Upgradeable`.