From ddeac0733f9e50fa817660b9af7171643405ff0a Mon Sep 17 00:00:00 2001 From: Ali Serag Date: Wed, 22 Apr 2026 20:08:16 -0500 Subject: [PATCH 1/2] docs: apply SEO/GEO audit recommendations + fix foundry CLI command - Audit README improvements (H1 expansion, badges, About Flow footer) - Fix incorrect Foundry install command (foundry install -> forge install) --- README.md | 49 ++++++++++++++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 6ed2f79..0b4a079 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,44 @@ -## Flow Solidity Utilities +# flow-sol-utils — Solidity Utility Contracts for Flow EVM -This repository contains a collection of Solidity contracts uniquely useful to building on EVM on Flow. You'll find -libraries, interface and abstract contracts, as well as contract implementations you may find useful in your own -projects. +[![License](https://img.shields.io/badge/license-Unlicense-blue.svg)](./LICENSE) +[![Release](https://img.shields.io/github/v/release/onflow/flow-sol-utils?include_prereleases&sort=semver)](https://github.com/onflow/flow-sol-utils/releases) +[![Discord](https://img.shields.io/badge/discord-flow-5865F2?logo=discord&logoColor=white)](https://discord.gg/flow) +[![Built on Flow](https://img.shields.io/badge/built%20on-Flow-00EF8B)](https://flow.com) +[![Foundry](https://img.shields.io/badge/built%20with-Foundry-black)](https://book.getfoundry.sh/) +## Overview -### Contracts +This repository contains a collection of Solidity contracts uniquely useful to building on EVM on Flow. You'll find libraries, interface and abstract contracts, as well as contract implementations you may find useful in your own projects. -* WFLOW - the equivalent of WETH on Ethereum, a wrapped version of FLOW token. - * Deployed to `0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e` on Flow [Testnet](https://evm-testnet.flowscan.io/token/0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e?tab=contract) & [Mainnet](https://evm.flowscan.io/token/0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e?tab=contract) -* CadenceArchUtils - a library of utility functions for working with Cadence Arch precompiles. -* CadenceRandomConsumer - a contract that assists in the implementation of secure onchain randomness, intended to make - the implementation of commit-reveal schemes easier to incorporate into your own projects. -* Xorshift128plus - an example pseudo-random number generator contract, helping you generate unique random numbers from - onchain random sources. +## Contracts -### Installation +* **WFLOW** — the equivalent of WETH on Ethereum, a wrapped version of the FLOW token. + * Deployed to `0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e` on Flow [Testnet](https://evm-testnet.flowscan.io/token/0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e?tab=contract) and [Mainnet](https://evm.flowscan.io/token/0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e?tab=contract). +* **CadenceArchUtils** — a library of utility functions for working with Cadence Arch precompiles. +* **CadenceRandomConsumer** — a contract that assists in implementing secure onchain randomness, intended to make commit-reveal schemes easier to incorporate into your own projects. +* **Xorshift128plus** — an example pseudo-random number generator contract, helping you generate unique random numbers from onchain random sources. -#### Foundry +## Installation -To install these contracts using Foundry, you can use the following command: +### Foundry + +To install these contracts using Foundry: ```sh -foundry install onflow/flow-sol-utils +forge install onflow/flow-sol-utils ``` -#### Hardhat +### Hardhat -To install these contracts using Hardhat, you can use the following command: +To install these contracts using Hardhat: ```sh npm install @onflow/flow-sol-utils -``` \ No newline at end of file +``` +## About Flow + +This repo is part of the [Flow network](https://flow.com), a Layer 1 blockchain built for consumer applications, AI Agents, and DeFi at scale. + +- Developer docs: https://developers.flow.com +- Cadence language: https://cadence-lang.org +- Community: [Flow Discord](https://discord.gg/flow) · [Flow Forum](https://forum.flow.com) +- Governance: [Flow Improvement Proposals](https://github.com/onflow/flips) From aab150f3d5c143f6958b1453c92c5113cc2df4bc Mon Sep 17 00:00:00 2001 From: Ali Serag Date: Thu, 23 Apr 2026 15:40:22 -0500 Subject: [PATCH 2/2] docs: add AGENTS.md Adds the AGENTS.md open-standard file for AI coding agents. Every claim evidence-backed against Makefile, package.json, source tree, or equivalent manifest. Zero fabrication. --- AGENTS.md | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..a335384 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +# AGENTS.md + +This file provides guidance to AI coding agents (Claude Code, Codex, Cursor, Copilot, and others) working in this repository. It is loaded automatically on attach — keep it concise. + +## Overview + +`flow-sol-utils` is a Solidity utility library for Flow EVM, distributed as both a Foundry package (`forge install onflow/flow-sol-utils`) and an npm package (`@onflow/flow-sol-utils`). It provides a wrapped-FLOW token, helpers for the Cadence Arch pre-compile, and a commit-reveal randomness consumer backed by Flow's protocol-native randomness. The repository itself is a Foundry project — there is no in-repo Hardhat configuration; npm distribution only ships `src/**/*.sol` (see `package.json` `files`) for downstream Hardhat/other consumers. + +## Build and Test Commands + +Foundry is the only build system in this repo. Initialize the `forge-std` submodule on first checkout (`git submodule update --init --recursive`), then: + +- `forge build` — compile contracts to `out/`. +- `forge build --sizes` — compile and print contract sizes (CI equivalent). +- `forge test -vvv` — run the Foundry test suite with verbose traces (CI equivalent). +- `forge fmt` — format Solidity sources; `forge fmt --check` is enforced in CI. +- `forge install ` — add a new library submodule under `lib/`. + +CI (`.github/workflows/test.yml`) runs `forge fmt --check`, `forge build --sizes`, and `forge test -vvv` under `FOUNDRY_PROFILE=ci` on nightly Foundry. + +## Architecture + +Foundry layout, defined in `foundry.toml` (`src = "src"`, `out = "out"`, `libs = ["lib"]`): + +- `src/wflow/WETH9.sol` — Wrapped FLOW (WFLOW) ERC-20. Contract is named `WETH9` (forked from Dapphub WETH9, GPL-3) with `name = "Wrapped Flow"` / `symbol = "WFLOW"`. Deployed at `0xd3bF53DAC106A0290B0483EcBC89d40FcC961f3e` on Flow EVM Mainnet and Testnet (per `README.md`). Pragma `>=0.4.22 <0.6` — do not import from newer-pragma sources; integrate via its deployed address. +- `src/cadence-arch/CadenceArchUtils.sol` — library wrapping `staticcall` to the Cadence Arch pre-compile at `0x0000000000000000000000010000000000000001` (`flowBlockHeight()`, `getRandomSource(uint64)`, `revertibleRandom()`). +- `src/random/CadenceRandomConsumer.sol` — abstract contract implementing a commit-reveal scheme over `CadenceArchUtils`; consumers inherit and call `_requestRandomness` / `_fulfillRandomRequest`. +- `src/random/Xorshift128plus.sol` — `Xorshift128plus` PRG library seeded from a source of randomness plus salt. +- `src/random/test/TestCadenceRandomConsumer.sol` — in-`src/` test harness that exposes `CadenceRandomConsumer`'s internal functions. It ships to npm consumers because `package.json` `files` is `src/**/*.sol`. +- `test/random/CadenceRandomConsumer.t.sol` — forge-std test using `vm.mockCall` to stub the three Cadence Arch entry points. +- `lib/forge-std` — git submodule (`foundry-rs/forge-std`, see `.gitmodules`); the only external dependency. +- `flow.json` — Flow CLI config with emulator/testnet/mainnet endpoints; `contracts` and `deployments` are empty (this repo ships Solidity, not Cadence). + +## Conventions and Gotchas + +- All contracts except `WETH9.sol` use `pragma solidity ^0.8.19` under SPDX `Unlicense`. `WETH9.sol` is GPL-3 with pragma `>=0.4.22 <0.6` — treat it as a vendored artifact. +- `forge fmt --check` is a CI gate; run `forge fmt` before committing Solidity changes. +- The Cadence Arch pre-compile address lives in `CadenceArchUtils.cadenceArch` — do not hardcode it elsewhere. +- `revertibleRandom()` is revertible by callers; use `CadenceRandomConsumer`'s commit-reveal flow when the caller isn't trusted (see NatSpec on `CadenceRandomConsumer` and `CadenceArchUtils._revertibleRandom`). +- Tests must mock all three Arch calls (`flowBlockHeight()`, `getRandomSource(uint64)`, `revertibleRandom()`) — see `setUp()` in `test/random/CadenceRandomConsumer.t.sol`. +- `src/random/test/TestCadenceRandomConsumer.sol` is published to npm by design; if you move it to `test/`, also update `package.json` `files`. +- Commit messages: imperative mood, subject ≤72 chars (`CONTRIBUTING.md`). + +## Files Not to Modify + +- `lib/forge-std/**` — git submodule; update via `forge update forge-std`. +- `src/wflow/WETH9.sol` — vendored Dapphub WETH9; the deployed address is canonical on Flow EVM. +- `out/`, `cache/` — Foundry build artifacts (gitignored).