Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .github/workflows/pr-assessment.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@ on:
pull_request:
types:
- closed

jobs:
assess-pr-size-on-merge:
uses: rainlanguage/github-chore/.github/workflows/pr-assessment.yml@main
Expand Down
64 changes: 45 additions & 19 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,16 +1,21 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
This file provides guidance to Claude Code (claude.ai/code) when working with
code in this repository.

## Project Overview

Solidity interfaces for the Rainlang interpreter and utility libraries for implementing them. Part of the Rain Protocol ecosystem for onchain interpreted compute.
Solidity interfaces for the Rainlang interpreter and utility libraries for
implementing them. Part of the Rain Protocol ecosystem for onchain interpreted
compute.

License: DecentraLicense 1.0 (DCL-1.0). REUSE 3.2 compliant — all files need SPDX headers and copyright notices.
License: DecentraLicense 1.0 (DCL-1.0). REUSE 3.2 compliant — all files need
SPDX headers and copyright notices.

## Build & Development

Requires the Nix package manager. **Only use the nix version of Foundry**, not a system-installed one.
Requires the Nix package manager. **Only use the nix version of Foundry**, not a
system-installed one.

```bash
nix develop # Enter dev shell
Expand All @@ -20,54 +25,75 @@ rainix-sol-static # Static analysis (Slither)
rainix-sol-legal # License/REUSE compliance check
```

Compiler: Solidity 0.8.25, EVM target: cancun, optimizer enabled (1M runs). Fuzz tests run 2048 iterations.
Compiler: Solidity 0.8.25, EVM target: cancun, optimizer enabled (1M runs). Fuzz
tests run 2048 iterations.

All reverts use custom errors — no `revert("string")` or `require()` with string messages.
All reverts use custom errors — no `revert("string")` or `require()` with string
messages.

## Architecture

### Core Interfaces (`src/interface/`)

The current interface set (all in `src/interface/`):

- **IInterpreterV4** — Evaluates Rainlang bytecode. Stateless: returns stack results and state writes without persisting anything itself.
- **IInterpreterStoreV3** — Key-value state storage with namespace isolation per caller. `set()` for bulk writes, `get()` for reads.
- **IInterpreterCallerV4** — Defines `EvaluableV4` struct (interpreter + store + bytecode). Contracts that call the interpreter implement this.
- **IInterpreterV4** — Evaluates Rainlang bytecode. Stateless: returns stack
results and state writes without persisting anything itself.
- **IInterpreterStoreV3** — Key-value state storage with namespace isolation per
caller. `set()` for bulk writes, `get()` for reads.
- **IInterpreterCallerV4** — Defines `EvaluableV4` struct (interpreter + store +
bytecode). Contracts that call the interpreter implement this.
- **IParserV2** — Converts Rainlang source text to bytecode (`parse2()`).
- **ISubParserV4** — Extension point for custom literals and words in parsers.
- **IInterpreterExternV4** — External function dispatch with integrity checking.
- **IParserPragmaV1** — Pragma support (e.g. `usingWordsFrom`).

Deprecated v1/v2 interfaces live in `src/interface/deprecated/`. Deprecated interfaces should not be modified unless undeprecating (moving back to `src/interface/`).
Deprecated v1/v2 interfaces live in `src/interface/deprecated/`. Deprecated
interfaces should not be modified unless undeprecating (moving back to
`src/interface/`).

### Libraries (`src/lib/`)

- **LibBytecode** (`bytecode/`) — Parse and validate Rainlang bytecode structure (source counts, offsets, stack allocation, OOB checks).
- **LibContext** (`caller/`) — Build execution context arrays with signature verification (uses OZ SignatureChecker). Base context = `[msg.sender, calling_contract]`.
- **LibBytecode** (`bytecode/`) — Parse and validate Rainlang bytecode structure
(source counts, offsets, stack allocation, OOB checks).
- **LibContext** (`caller/`) — Build execution context arrays with signature
verification (uses OZ SignatureChecker). Base context =
`[msg.sender, calling_contract]`.
- **LibEvaluable** (`caller/`) — Hash utility for `EvaluableV4` structs.
- **LibNamespace** (`ns/`) — Qualifies state namespaces by hashing with sender address for caller isolation.
- **LibParseMeta** (`parse/`) — Bloom filter + fingerprint-based word lookup for parser metadata.
- **LibGenParseMeta** (`codegen/`) — Code generation for optimized parse metadata constants.
- **LibNamespace** (`ns/`) — Qualifies state namespaces by hashing with sender
address for caller isolation.
- **LibParseMeta** (`parse/`) — Bloom filter + fingerprint-based word lookup for
parser metadata.
- **LibGenParseMeta** (`codegen/`) — Code generation for optimized parse
metadata constants.

### Key Types

- `StackItem` — `bytes32`, the interpreter's stack value type
- `OperandV2` — `bytes32`, opcode operands
- `StateNamespace` / `FullyQualifiedNamespace` — `bytes32`, state isolation
- `SourceIndexV2` — `bytes32`, index into bytecode sources
- `EvaluableV4` — struct containing interpreter address, store address, and bytecode
- `EvaluableV4` — struct containing interpreter address, store address, and
bytecode

### Security Model

Interpreters must be resilient to malicious expressions. Eval is read-only; state changes go through a separate `set()` call. Namespace qualification ensures caller isolation. If eval reverts, no state changes persist.
Interpreters must be resilient to malicious expressions. Eval is read-only;
state changes go through a separate `set()` call. Namespace qualification
ensures caller isolation. If eval reverts, no state changes persist.

## Tests

Tests are in `test/src/lib/` mirroring the `src/lib/` structure. Test files use `.t.sol` suffix. Reference implementations used in differential testing append `Slow` to the library name, with no separating dot: `LibNamespaceSlow.sol`, `LibBytecodeSlow.sol`.
Tests are in `test/src/lib/` mirroring the `src/lib/` structure. Test files use
`.t.sol` suffix. Reference implementations used in differential testing append
`Slow` to the library name, with no separating dot: `LibNamespaceSlow.sol`,
`LibBytecodeSlow.sol`.

## Dependencies

Soldeer, installed into `dependencies/`. Imports carry the package version in the path (`rain-solmem-0.1.3/src/...`), so a version bump rewrites every import of that package.
Soldeer, installed into `dependencies/`. Imports carry the package version in
the path (`rain-solmem-0.1.3/src/...`), so a version bump rewrites every import
of that package.

## Branch Naming

Expand Down
9 changes: 5 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@ CI usage.

## Legal stuff

Everything is under DecentraLicense 1.0 (DCL-1.0) which can be found in `LICENSES/`.
Everything is under DecentraLicense 1.0 (DCL-1.0) which can be found in
`LICENSES/`.

This is basically `CAL-1.0` which is an open source license
https://opensource.org/license/cal-1-0
Expand All @@ -33,8 +34,8 @@ to those users as relevant, and that private keys remain private.
Roughly it's "not your keys, not your coins" aware, as close as we could get in
legalese.

This is the default situation on permissionless blockchains, so shouldn't require
any additional effort by dev-users to adhere to the license terms.
This is the default situation on permissionless blockchains, so shouldn't
require any additional effort by dev-users to adhere to the license terms.

This repo is REUSE 3.2 compliant https://reuse.software/spec-3.2/ and compatible
with `reuse` tooling (also available in the nix shell here).
Expand All @@ -47,4 +48,4 @@ nix develop -c rainix-sol-legal

Contributions are welcome **under the same license** as above.

Contributors agree and warrant that their contributions are compliant.
Contributors agree and warrant that their contributions are compliant.
Loading