@layerzerolabs/protocol-stellar-v2 0.2.34 → 0.2.36

package/docs/layerzero-v2-on-stellar.md

@@ -221,12 +221,16 @@ sequenceDiagram
 
 ## Stellar-specific considerations
 
-Two core differences between Soroban and EVM require protocol-level adaptations:
+Several differences between Soroban and EVM require protocol-level adaptations:
 
 1. Stellar's variable-length address model differs from LayerZero's fixed
    bytes32 address abstraction
 2. Soroban's Time-To-Live (TTL)-based storage model requires active state
    maintenance, unlike EVM's persistent storage
+3. Soroban's 200-read-per-transaction storage limit makes the lazy inbound
+   nonce model susceptible to denial-of-service for certain OApps
+4. Soroban prohibits reentrancy, requiring alternative patterns for cross-contract
+   call flows
 
 ### Constraint 1: bytes32 address format mismatch
 
@@ -296,7 +300,47 @@ constraints may evolve.
 - Hard upper cap on extension targets (e.g., 1 year) to prevent excessive fees
 - TTL parameters can be permanently frozen once the ecosystem stabilizes
 
-### Constraint 3: Reentrancy prohibition
+### Constraint 3: Storage read limits
+
+Soroban enforces a hard limit of 200 persistent/temporary storage reads per
+transaction. Under the lazy inbound nonce model used in EVM, the `inbound_nonce`
+is not stored directly — it is computed on the fly by iterating forward from the
+last checkpoint (`lazy_inbound_nonce`) and probing storage for each consecutive
+payload hash. The same iterative check occurs during `clear`, which must verify
+that all nonces between the checkpoint and the target nonce have been verified.
+
+For certain OApps, failed `lz_receive` executions can create nonce gaps that
+grow over time. Under the lazy model, clearing subsequent messages requires
+iterating across these gaps, and the accumulated storage reads can exceed the
+200-read limit, making the messaging path susceptible to denial-of-service.
+
+**Solution: Eager inbound nonce with pending nonce list (Solana model)**
+
+Stellar adopts the same inbound nonce model used by LayerZero V2 on Solana.
+Instead of lazily computing the inbound nonce via storage probing, the
+`inbound_nonce` is stored directly and updated eagerly during verification:
+
+1. **`PendingInboundNonces`**: A sorted list of out-of-order verified nonces is
+   maintained in a single storage entry per path. When a message is verified
+   (or skipped/nilified), its nonce is inserted into this list.
+
+2. **Drain on insert**: After each insertion, consecutive nonces at the front of
+   the list are drained to advance the `inbound_nonce`. For example, if
+   `inbound_nonce = 3` and the pending list becomes `[4, 5, 7]`, nonces 4 and 5
+   are drained, advancing `inbound_nonce` to 5.
+
+3. **O(1) clear**: The `clear_payload` operation becomes a simple comparison
+   (`nonce <= inbound_nonce`) with no iteration or storage probing.
+
+4. **Bounded list size**: The pending list is capped at 256 entries
+   (`PENDING_INBOUND_NONCE_MAX_LEN`). Nonces beyond `inbound_nonce + 256`
+   cannot be verified, preventing unbounded memory growth and limiting the
+   maximum storage reads per verify operation.
+
+This eliminates the iterative storage reads that could cause DoS under the lazy
+model, keeping all operations within Soroban's transaction resource limits.
+
+### Constraint 4: Reentrancy prohibition
 
 Soroban prohibits reentrancy—a contract cannot call itself, directly or
 indirectly, within the same transaction. This fundamental difference from EVM

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@layerzerolabs/protocol-stellar-v2",
-  "version": "0.2.34",
+  "version": "0.2.36",
   "private": false,
   "devDependencies": {
     "@types/node": "^22.18.6",
     "tsx": "^4.19.3",
     "typescript": "^5.8.2",
-    "@layerzerolabs/common-node-utils": "0.2.34",
-    "@layerzerolabs/vm-tooling-stellar": "0.2.34"
+    "@layerzerolabs/common-node-utils": "0.2.36",
+    "@layerzerolabs/vm-tooling-stellar": "0.2.36"
   },
   "publishConfig": {
     "access": "restricted",