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,32 @@
     "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"
   ]
 }

.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,76 @@ 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%"

.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

.vscode/settings.json

@@ -13,5 +13,8 @@
   "editor.formatOnSave": true,
   "[solidity]": {
     "editor.defaultFormatter": "JuanBlanco.solidity"
+  },
+  "chat.tools.terminal.autoApprove": {
+    "forge": true
   }
 }