feat: implement BLE swarm registry system with dual-chain support

.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,21 @@
     "Frontends",
     "testuser",
     "testhandle",
-    "douglasacost"
+    "douglasacost",
+    "IBEACON",
+    "AABBCCDD",
+    "SSTORE",
+    "Permissionless",
+    "Reentrancy",
+    "SFID",
+    "EXTCODECOPY",
+    "solady",
+    "SLOAD",
+    "Bitmask",
+    "mstore",
+    "MBOND",
+    "USCA",
+    "USNY",
+    "usca"
   ]
 }

.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,4 @@ jobs:
         run: yarn lint
 
       - name: Run tests
-        run: forge test --zksync
+        run: forge test

.gitmodules

@@ -10,3 +10,6 @@
 [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

.vscode/settings.json

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

foundry.lock

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

logs/deploy_l1_bridge.log

@@ -0,0 +1,32 @@
+Compiling 1 files with Solc 0.8.26
+Solc 0.8.26 finished in 2.60s
+Compiler run successful!
+Script ran successfully.
+
+== Logs ==
+  Deployed L1Bridge at 0x2D02b651Ea9630351719c8c55210e042e940d69a
+  Granted MINTER_ROLE on NodlL1(0x6dd0E17ec6fE56c5f58a0Fe2Bb813B9b5cc25990) to bridge
+
+## Setting up 1 EVM.
+
+==========================
+
+Chain 1
+
+Estimated gas price: 0.222068762 gwei
+
+Estimated total gas used for script: 2685066
+
+Estimated amount required: 0.000596269282508292 ETH
+
+==========================
+
+
+==========================
+
+ONCHAIN EXECUTION COMPLETE & SUCCESSFUL.
+
+Transactions saved to: /Users/alex/Documents/rollup/broadcast/DeployL1Bridge.s.sol/1/run-latest.json
+
+Sensitive values saved to: /Users/alex/Documents/rollup/cache/DeployL1Bridge.s.sol/1/run-latest.json
+

logs/deploy_l1_nodl.log

@@ -0,0 +1,29 @@
+No files changed, compilation skipped
+Script ran successfully.
+
+== Logs ==
+  Deployed L1Nodl at 0x6dd0E17ec6fE56c5f58a0Fe2Bb813B9b5cc25990
+
+## Setting up 1 EVM.
+
+==========================
+
+Chain 1
+
+Estimated gas price: 0.251645298 gwei
+
+Estimated total gas used for script: 4998146
+
+Estimated amount required: 0.001257759939617508 ETH
+
+==========================
+
+
+==========================
+
+ONCHAIN EXECUTION COMPLETE & SUCCESSFUL.
+
+Transactions saved to: /Users/alex/Documents/rollup/broadcast/DeployL1Nodl.s.sol/1/run-latest.json
+
+Sensitive values saved to: /Users/alex/Documents/rollup/cache/DeployL1Nodl.s.sol/1/run-latest.json
+

logs/deploy_l2_bridge.log

@@ -0,0 +1,98 @@
+Compiling 1 files with Solc 0.8.26
+Solc 0.8.26 finished in 1.70s
+Compiler run successful!
+
+Compiling 1 files with zksolc and solc 0.8.26
+zksolc and solc 0.8.26 finished in 4.05s
+Compiler run successful with warnings:
+Warning
+ZKsync Era comes with native account abstraction support, and therefore the initiator of a
+transaction might be different from the contract calling your code. It is highly recommended NOT
+to rely on tx.origin, but use msg.sender instead.
+Learn more about Account Abstraction at https://docs.zksync.io/build/developer-reference/account-abstraction/
+You may disable this warning with:
+    a. `suppressedWarnings = ["txorigin"]` in standard JSON.
+    b. `--suppress-warnings txorigin` in the CLI.
+   --> lib/era-contracts/l1-contracts/contracts/vendor/AddressAliasHelper.sol:56:42    |
+ 56 |             _recipient = _prevMsgSender == tx.origin
+    |                                            ^^^^^^^^^
+
+Warning
+EraVM does not use bytecode for contract deployment. Instead, it refers to contracts using their bytecode hashes.
+In order to deploy a contract, please use the `new` operator in Solidity instead of raw 'create'/'create2' in assembly.
+In Solidity v0.6 and older, it can be a false-positive warning if there is 'create(' or 'create2(' in comments within assembly.
+Learn more about CREATE/CREATE2 EraVM limitations at https://docs.zksync.io/zksync-protocol/differences/evm-instructions#create-create2
+You may disable this warning with:
+    1. `suppressedWarnings = ["assemblycreate"]` in standard JSON.
+    2. `--suppress-warnings assemblycreate` in the CLI.
+    --> lib/forge-std/src/StdCheats.sol:494:19     |
+ 494 |             addr := create(0, add(bytecode, 0x20), mload(bytecode))
+     |                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Warning
+EraVM does not use bytecode for contract deployment. Instead, it refers to contracts using their bytecode hashes.
+In order to deploy a contract, please use the `new` operator in Solidity instead of raw 'create'/'create2' in assembly.
+In Solidity v0.6 and older, it can be a false-positive warning if there is 'create(' or 'create2(' in comments within assembly.
+Learn more about CREATE/CREATE2 EraVM limitations at https://docs.zksync.io/zksync-protocol/differences/evm-instructions#create-create2
+You may disable this warning with:
+    1. `suppressedWarnings = ["assemblycreate"]` in standard JSON.
+    2. `--suppress-warnings assemblycreate` in the CLI.
+    --> lib/forge-std/src/StdCheats.sol:504:19     |
+ 504 |             addr := create(0, add(bytecode, 0x20), mload(bytecode))
+     |                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Warning
+EraVM does not use bytecode for contract deployment. Instead, it refers to contracts using their bytecode hashes.
+In order to deploy a contract, please use the `new` operator in Solidity instead of raw 'create'/'create2' in assembly.
+In Solidity v0.6 and older, it can be a false-positive warning if there is 'create(' or 'create2(' in comments within assembly.
+Learn more about CREATE/CREATE2 EraVM limitations at https://docs.zksync.io/zksync-protocol/differences/evm-instructions#create-create2
+You may disable this warning with:
+    1. `suppressedWarnings = ["assemblycreate"]` in standard JSON.
+    2. `--suppress-warnings assemblycreate` in the CLI.
+    --> lib/forge-std/src/StdCheats.sol:515:19     |
+ 515 |             addr := create(val, add(bytecode, 0x20), mload(bytecode))
+     |                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Warning
+EraVM does not use bytecode for contract deployment. Instead, it refers to contracts using their bytecode hashes.
+In order to deploy a contract, please use the `new` operator in Solidity instead of raw 'create'/'create2' in assembly.
+In Solidity v0.6 and older, it can be a false-positive warning if there is 'create(' or 'create2(' in comments within assembly.
+Learn more about CREATE/CREATE2 EraVM limitations at https://docs.zksync.io/zksync-protocol/differences/evm-instructions#create-create2
+You may disable this warning with:
+    1. `suppressedWarnings = ["assemblycreate"]` in standard JSON.
+    2. `--suppress-warnings assemblycreate` in the CLI.
+    --> lib/forge-std/src/StdCheats.sol:525:19     |
+ 525 |             addr := create(val, add(bytecode, 0x20), mload(bytecode))
+     |                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+2025-10-15T00:35:52.095529Z ERROR backendhandler: failed to get block err=failed to get block; error sending request for url (https://mainnet.era.zksync.io/); operation timed out number=65260273
+2025-10-15T00:35:52.096034Z ERROR sharedbackend: Failed to send/recv `block_hash` err=failed to get block hash for 65260273: failed to get block; error sending request for url (https://mainnet.era.zksync.io/); operation timed out number=65260273
+Script ran successfully.
+
+== Logs ==
+  Deployed L2Bridge at 0x2c1B65dA72d5Cf19b41dE6eDcCFB7DD83d1B529E
+  Granted MINTER_ROLE on NODL(0xBD4372e44c5eE654dd838304006E1f0f69983154) to bridge
+
+## Setting up 1 EVM.
+
+==========================
+
+Chain 324
+
+Estimated gas price: 0.090500001 gwei
+
+Estimated total gas used for script: 209410861
+
+Estimated amount required: 0.018951683129910861 ETH
+
+==========================
+
+
+==========================
+
+ONCHAIN EXECUTION COMPLETE & SUCCESSFUL.
+
+Transactions saved to: /Users/alex/Documents/rollup/broadcast/DeployL2Bridge.s.sol/324/run-latest.json
+
+Sensitive values saved to: /Users/alex/Documents/rollup/cache/DeployL2Bridge.s.sol/324/run-latest.json
+

remappings.txt

@@ -1 +1,2 @@
-@openzeppelin=lib/openzeppelin-contracts/
+@openzeppelin=lib/openzeppelin-contracts/
+solady/=lib/solady/src/