2026 01 29 audit

README.md

@@ -1 +1,21 @@
 # rain.sol.codegen
+
+Solidity native tooling to generate Solidity code.
+
+Notably builds a valid Solidity file (pragma, etc.) that passes foundry
+formatting cleanly, that can build the constant caches needed for prebuilt
+function pointer tables to ensure runtime gas efficiency.
+
+Includes interfaces for the interpreter and sub parsers/externs for Rain
+contracts to implement and be compatible with the code generation functions here.
+
+`script/BuildPointers.sol` includes an example implementation and
+`.github/workflows/git-clean.yaml` an example CI action to show how to build
+pointers cleanly and ensure that the source code does not become out of sync with
+the built artifacts when merging new code.
+
+Generated code is intended to be imported downstream into contracts that may
+themselves expose pointers to be included in the generated code. This circular
+dependency means the pointers may need to be built several times until they
+produce a stable output where the pointers do not move, and therefore do not
+break the codehash over the contract that includes the pointers.

foundry.lock

@@ -1,8 +1,8 @@
 {
   "lib/forge-std": {
-    "rev": "b8f065fda83b8cd94a6b2fec8fcd911dc3b444fd"
+    "rev": "1801b0541f4fda118a10798fd3486bb7051c5dd6"
   },
   "lib/rain.math.binary": {
-    "rev": "f44f846a43928ba0a7ed4a7bb810a8933e23cce1"
+    "rev": "122a490bb1869c7533f108cb8b371d75de9db60f"
   }
 }

script/BuildPointers.sol

@@ -7,7 +7,13 @@ import {LibFs} from "../src/lib/LibFs.sol";
 import {LibCodeGen} from "../src/lib/LibCodeGen.sol";
 import {CodeGennable} from "../test/concrete/CodeGennable.sol";
 
+/// @title BuildPointers
+/// @notice Script to build the pointers file for the CodeGennable contract.
+/// @dev This shows an example of how to use the bytes constant generation
+/// utility in LibCodeGen.
 contract BuildPointers is Script {
+    /// Builds the pointers file for the CodeGennable contract to show an example
+    /// of how to use the bytes constant generation utility.
     function run() external {
         CodeGennable codeGennable = new CodeGennable();
 
@@ -16,13 +22,15 @@ contract BuildPointers is Script {
             address(codeGennable),
             "CodeGennable",
             string.concat(
-                LibCodeGen.bytesConstantString(vm, "/// @dev Some bytes comment.", "SOME_BYTES_CONSTANT", hex"12345678"),
                 LibCodeGen.bytesConstantString(
-                    vm,
-                    "/// @dev Longer constant.",
-                    "LONGER_BYTES_CONSTANT",
-                    hex"e2bafcba65b2c99d33f5096307bc57c2e7f195d2a178f56e45d720bb64344998e2bafcba65b2c99d33f5096307bc57c2e7f195d2a178f56e45d720bb64344998"
-                )
+                    vm, "/// @dev Some bytes comment.", "SOME_BYTES_CONSTANT", hex"12345678"
+                ),
+                LibCodeGen.bytesConstantString(
+                        vm,
+                        "/// @dev Longer constant.",
+                        "LONGER_BYTES_CONSTANT",
+                        hex"e2bafcba65b2c99d33f5096307bc57c2e7f195d2a178f56e45d720bb64344998e2bafcba65b2c99d33f5096307bc57c2e7f195d2a178f56e45d720bb64344998"
+                    )
             )
         );
     }

src/interface/IIntegrityToolingV1.sol

@@ -2,6 +2,19 @@
 // SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
 pragma solidity ^0.8.25;
 
+/// @title IIntegrityToolingV1
+/// Implemented by any contract that exposes integrity check functions for the
+/// Rain interpreter. Ostensibly this is for the interpreter itself and also
+/// extension points such as externs. These integrity checks are for the opcodes
+/// tooled by IOpcodeToolingV1 implementations.
 interface IIntegrityToolingV1 {
+    /// Builds integrity function pointers.
+    /// This is intended for use by the Rain interpreter to run integrity checks
+    /// over rainlang code before it is used/deployed/executed. The expectation
+    /// is that the pointers will be built ahead of time and cached in a constant
+    /// for efficiency. As the process is deterministic for a given source and
+    /// compiler configuration, the output can be tested against the used value
+    /// in CI and the translation from source to pointers can also be tested in
+    /// CI. See .github/workflows/git-clean.yaml for an example of such a test.
     function buildIntegrityFunctionPointers() external view returns (bytes memory);
 }

src/interface/IOpcodeToolingV1.sol

@@ -2,6 +2,18 @@
 // SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
 pragma solidity ^0.8.25;
 
+/// @title IOpcodeToolingV1
+/// Implemented by any contract that exposes opcode functions (new words) for the
+/// Rain interpreter. Ostensibly this is for the interpreter itself and also
+/// extension points such as externs.
 interface IOpcodeToolingV1 {
+    /// Builds opcode function pointers.
+    /// This is intended for use by the Rain interpreter to run opcodes
+    /// implementing rainlang execution logic. The expectation is that the
+    /// pointers will be built ahead of time and cached in a constant for
+    /// efficiency. As the process is deterministic for a given source and
+    /// compiler configuration, the output can be tested against the used value
+    /// in CI and the translation from source to pointers can also be tested in
+    /// CI. See .github/workflows/git-clean.yaml for an example of such a test.
     function buildOpcodeFunctionPointers() external view returns (bytes memory);
 }

src/interface/IParserToolingV1.sol

@@ -2,8 +2,28 @@
 // SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
 pragma solidity ^0.8.25;
 
+/// @title IParserToolingV1
+/// Implemented by any contract that exposes parser tooling functions for the
+/// Rain interpreter. Ostensibly this is for the interpreter itself while sub
+/// parsers have a separate interface.
 interface IParserToolingV1 {
+    /// Builds operand handler function pointers.
+    /// This is intended for use by the Rain interpreter to run operand handling
+    /// logic when parsing rainlang code. The expectation is that the pointers
+    /// will be built ahead of time and cached in a constant for efficiency. As
+    /// the process is deterministic for a given source and compiler
+    /// configuration, the output can be tested against the used value in CI and
+    /// the translation from source to pointers can also be tested in CI. See
+    /// .github/workflows/git-clean.yaml for an example of such a test.
     function buildOperandHandlerFunctionPointers() external pure returns (bytes memory);
 
+    /// Builds literal parser function pointers.
+    /// This is intended for use by the Rain interpreter to run literal parsing
+    /// logic when parsing rainlang code. The expectation is that the pointers
+    /// will be built ahead of time and cached in a constant for efficiency. As
+    /// the process is deterministic for a given source and compiler
+    /// configuration, the output can be tested against the used value in CI and
+    /// the translation from source to pointers can also be tested in CI. See
+    /// .github/workflows/git-clean.yaml for an example of such a test.
     function buildLiteralParserFunctionPointers() external pure returns (bytes memory);
 }

src/interface/ISubParserToolingV1.sol

@@ -2,6 +2,17 @@
 // SPDX-FileCopyrightText: Copyright (c) 2020 Rain Open Source Software Ltd
 pragma solidity ^0.8.25;
 
+/// @title ISubParserToolingV1
+/// Implemented by any contract that exposes sub parser tooling functions for the
+/// Rain interpreter.
 interface ISubParserToolingV1 {
+    /// Builds sub parser word parsers.
+    /// This is intended for use by the Rain interpreter to run sub parser word
+    /// parsing logic when parsing rainlang code. The expectation is that the
+    /// parsers will be built ahead of time and cached in a constant for
+    /// efficiency. As the process is deterministic for a given source and
+    /// compiler configuration, the output can be tested against the used value
+    /// in CI and the translation from source to parsers can also be tested in
+    /// CI. See .github/workflows/git-clean.yaml for an example of such a test.
     function buildSubParserWordParsers() external pure returns (bytes memory);
 }