feat: implement BLE swarm registry system

.agent/rules/solidity_zksync.md

@@ -0,0 +1,33 @@
+# Solidity & ZkSync Development Standards
+
+## Toolchain & Environment
+- **Primary Tool**: `forge` (ZkSync fork). Use for compilation, testing, and generic scripting.
+- **Secondary Tool**: `hardhat`. Use only when `forge` encounters compatibility issues (e.g., complex deployments, specific plugin needs).
+- **Network Target**: ZkSync Era (Layer 2).
+- **Solidity Version**: `^0.8.20` (or `0.8.24` if strictly supported by the zk-compiler).
+
+## Modern Solidity Best Practices
+- **Safety First**:
+  - **Checks-Effects-Interactions (CEI)** pattern must be strictly followed.
+  - When a contract requires an owner (e.g., admin-configurable parameters), prefer `Ownable2Step` over `Ownable`. Do **not** add ownership to contracts that don't need it — many contracts are fully permissionless by design.
+  - Prefer `ReentrancyGuard` for external calls where appropriate.
+- **Gas & Efficiency**:
+  - Use **Custom Errors** (`error MyError();`) instead of `require` strings.
+  - Use `mapping` over arrays for membership checks where possible.
+  - Minimize on-chain storage; use events for off-chain indexing.
+
+## Testing Standards
+- **Framework**: Foundry (Forge).
+- **Methodology**:
+  - **Unit Tests**: Comprehensive coverage for all functions.
+  - **Fuzz Testing**: Required for arithmetic and purely functional logic.
+  - **Invariant Testing**: Define invariants for stateful system properties.
+- **Naming Convention**:
+  - `test_Description`
+  - `testFuzz_Description`
+  - `test_RevertIf_Condition`
+
+## ZkSync Specifics
+- **System Contracts**: Be aware of ZkSync system contracts (e.g., `ContractDeployer`, `L2EthToken`) when interacting with low-level features.
+- **Gas Model**: Account for ZkSync's different gas metering if performing low-level optimization.
+- **Compiler Differences**: Be mindful of differences between `solc` and `zksolc` (e.g., `create2` address derivation).

.cspell.json

@@ -12,7 +12,8 @@
     "deployments-zk",
     "cache_hardhat-zk",
     "zkout",
-    "clk-gateway/src/validators.test.ts"
+    "clk-gateway/src/validators.test.ts",
+    "src/swarms/doc/iso3166-2"
   ],
   "ignoreWords": [
     "NODL",
@@ -60,6 +61,39 @@
     "Frontends",
     "testuser",
     "testhandle",
-    "douglasacost"
+    "douglasacost",
+    "IBEACON",
+    "AABBCCDD",
+    "SSTORE",
+    "Permissionless",
+    "Reentrancy",
+    "SFID",
+    "EXTCODECOPY",
+    "solady",
+    "SLOAD",
+    "Bitmask",
+    "mstore",
+    "MBOND",
+    "USCA",
+    "USNY",
+    "usca",
+    "UUPS",
+    "reinitializer",
+    "Reinitializer",
+    "Initializable",
+    "bitshift",
+    "timelock",
+    "iface",
+    "pkill",
+    "Blockscout",
+    "REINIT",
+    "reinit",
+    "EDDYSTONE",
+    "Eddystone",
+    "Estimote",
+    "backgrounded",
+    "reconstructable",
+    "Württemberg",
+    "delegatecall"
   ]
 }

.github/copilot-instructions.md

@@ -0,0 +1,50 @@
+# Solidity & ZkSync Development Standards
+
+## Toolchain & Environment
+
+- **Primary Tool**: `forge` (ZkSync fork). Use for compilation, testing, and generic scripting.
+- **Secondary Tool**: `hardhat`. Use only when `forge` encounters compatibility issues (e.g., complex deployments, specific plugin needs).
+- **Network Target**: ZkSync Era (Layer 2).
+- **Solidity Version**: `^0.8.20` (or `0.8.24` if strictly supported by the zk-compiler).
+
+## Modern Solidity Best Practices
+
+- **Safety First**:
+  - **Checks-Effects-Interactions (CEI)** pattern must be strictly followed.
+  - Use `Ownable2Step` over `Ownable` for privileged access.
+  - Prefer `ReentrancyGuard` for external calls where appropriate.
+- **Gas & Efficiency**:
+  - Use **Custom Errors** (`error MyError();`) instead of `require` strings.
+  - Use `mapping` over arrays for membership checks where possible.
+  - Minimize on-chain storage; use events for off-chain indexing.
+
+## Testing Standards
+
+- **Framework**: Foundry (Forge).
+- **Methodology**:
+  - **Unit Tests**: Comprehensive coverage for all functions.
+  - **Fuzz Testing**: Required for arithmetic and purely functional logic.
+  - **Invariant Testing**: Define invariants for stateful system properties.
+- **Naming Convention**:
+  - `test_Description`
+  - `testFuzz_Description`
+  - `test_RevertIf_Condition`
+
+## ZkSync Specifics
+
+- **System Contracts**: Be aware of ZkSync system contracts (e.g., `ContractDeployer`, `L2EthToken`) when interacting with low-level features.
+- **Gas Model**: Account for ZkSync's different gas metering if performing low-level optimization.
+- **Compiler Differences**: Be mindful of differences between `solc` and `zksolc` (e.g., `create2` address derivation).
+
+## L1-Only Contracts (No --zksync flag)
+
+The following contracts use opcodes/patterns incompatible with ZkSync Era and must be built/tested **without** the `--zksync` flag:
+
+- **SwarmRegistryL1**: Uses `SSTORE2` (relies on `EXTCODECOPY` which is unsupported on ZkSync).
+
+For these contracts, use:
+
+```bash
+forge build --match-path src/swarms/SwarmRegistryL1.sol
+forge test --match-path test/SwarmRegistryL1.t.sol
+```

.github/workflows/checks.yml

@@ -34,4 +34,107 @@ jobs:
         run: yarn lint
 
       - name: Run tests
-        run: forge test --zksync
+        run: forge test
+
+  Coverage:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+    container:
+      image: ghcr.io/nodlecode/devcontainer-rollup
+      options: --user root
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install dependencies
+        run: yarn
+
+      - name: Run coverage
+        run: forge coverage --match-path "test/{Swarm*,ServiceProvider,FleetIdentity}*.t.sol" --ir-minimum --report lcov --report-file coverage.lcov
+
+      - name: Upload coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.lcov
+          retention-days: 30
+
+      - name: Install lcov
+        run: apt-get update && apt-get install -y lcov
+
+      - name: Report coverage to PR
+        uses: zgosalvez/github-actions-report-lcov@v4
+        with:
+          coverage-files: coverage.lcov
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          update-comment: true
+          working-directory: ./
+
+      - name: Check line coverage threshold
+        run: |
+          # Extract line coverage from lcov report for src/swarms/ contracts only
+          # Parse lcov format: find swarm file sections and sum their LF/LH values
+          LINES_FOUND=$(awk '
+            /^SF:.*src\/swarms\// { in_swarm = 1 }
+            /^end_of_record/ { in_swarm = 0 }
+            in_swarm && /^LF:/ { sum += substr($0, 4) }
+            END { print sum+0 }
+          ' coverage.lcov)
+
+          LINES_HIT=$(awk '
+            /^SF:.*src\/swarms\// { in_swarm = 1 }
+            /^end_of_record/ { in_swarm = 0 }
+            in_swarm && /^LH:/ { sum += substr($0, 4) }
+            END { print sum+0 }
+          ' coverage.lcov)
+
+          if [ "$LINES_FOUND" -eq 0 ]; then
+            echo "Error: No lines found in coverage report for src/swarms/"
+            exit 1
+          fi
+
+          COVERAGE=$(awk "BEGIN {printf \"%.2f\", ($LINES_HIT / $LINES_FOUND) * 100}")
+          echo "Swarms line coverage: $COVERAGE% ($LINES_HIT / $LINES_FOUND lines)"
+
+          # Check if coverage is below 95%
+          THRESHOLD=95
+          if awk "BEGIN {exit !($COVERAGE < $THRESHOLD)}"; then
+            echo "Error: Line coverage ($COVERAGE%) is below the required threshold ($THRESHOLD%)"
+            exit 1
+          fi
+
+          echo "Coverage check passed: $COVERAGE% >= $THRESHOLD%"
+
+  Specification-PDF:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request' && github.base_ref == 'main'
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install npm dependencies
+        working-directory: src/swarms/doc/spec
+        run: npm install --no-save @mermaid-js/mermaid-cli md-to-pdf
+
+      - name: Install Puppeteer browser
+        run: npx puppeteer browsers install chrome
+
+      - name: Build specification PDF
+        working-directory: src/swarms/doc/spec
+        run: bash build.sh
+
+      - name: Upload specification PDF
+        uses: actions/upload-artifact@v4
+        with:
+          name: swarm-specification
+          path: src/swarms/doc/spec/swarm-specification.pdf
+          retention-days: 30

.gitmodules

@@ -10,3 +10,9 @@
 [submodule "lib/era-contracts"]
 	path = lib/era-contracts
 	url = https://github.com/matter-labs/era-contracts
+[submodule "lib/solady"]
+	path = lib/solady
+	url = https://github.com/vectorized/solady
+[submodule "lib/openzeppelin-contracts-upgradeable"]
+	path = lib/openzeppelin-contracts-upgradeable
+	url = https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable

foundry.lock

@@ -0,0 +1,26 @@
+{
+  "lib/forge-std": {
+    "rev": "1eea5bae12ae557d589f9f0f0edae2faa47cb262"
+  },
+  "lib/zksync-storage-proofs": {
+    "rev": "4b20401ce44c1ec966a29d893694f65db885304b"
+  },
+  "lib/solady": {
+    "tag": {
+      "name": "v0.1.26",
+      "rev": "acd959aa4bd04720d640bf4e6a5c71037510cc4b"
+    }
+  },
+  "lib/era-contracts": {
+    "rev": "84d5e3716f645909e8144c7d50af9dd6dd9ded62"
+  },
+  "lib/openzeppelin-contracts-upgradeable": {
+    "tag": {
+      "name": "v5.6.1",
+      "rev": "7bf4727aacdbfaa0f36cbd664654d0c9e1dc52bf"
+    }
+  },
+  "lib/openzeppelin-contracts": {
+    "rev": "e4f70216d759d8e6a64144a9e1f7bbeed78e7079"
+  }
+}

foundry.toml

@@ -8,3 +8,21 @@ solc = "0.8.26"
 
 # necessary as some of the zksync contracts are big
 via_ir = true
+optimizer = true
+optimizer_runs = 200
+
+[lint]
+# Exclude ERC20 transfer warning - false positive for ERC721.transferFrom in tests
+exclude_lints = ["erc20-unchecked-transfer"]
+
+[profile.zksync]
+src = "src"
+out = "zkout"
+libs = ["lib"]
+solc = "0.8.26"
+via_ir = true
+optimizer = true
+optimizer_runs = 200
+# Exclude L1-only contracts that use SSTORE2/EXTCODECOPY
+ignored_error_codes = []
+ignored_warnings_from = []