@layerzerolabs/protocol-stellar-v2 0.2.20 → 0.2.21

package/sdk/test/suites/localnet.ts

@@ -1,11 +1,22 @@
 import axios from 'axios';
 import { $, sleep } from 'zx';
 
-import { DEFAULT_DEPLOYER, EXECUTOR_ADMIN, FRIENDBOT_URL, ZRO_DISTRIBUTOR } from './constants';
+import {
+    DEFAULT_DEPLOYER,
+    EXECUTOR_ADMIN,
+    FRIENDBOT_URL,
+    RPC_URL,
+    ZRO_DISTRIBUTOR,
+} from './constants';
 import { deployNativeSac, deployZroToken } from './deploy';
 
 const CONTAINER_NAME = 'stellar-localnet';
-const QUICKSTART_IMAGE = 'stellar/quickstart';
+const QUICKSTART_IMAGE = 'stellar/quickstart:testing';
+
+// Timeout configuration (in milliseconds)
+const STARTUP_TIMEOUT_MS = 300_000; // 5 minutes total timeout for localnet startup
+const REQUEST_TIMEOUT_MS = 10_000; // 10 seconds per request
+const RETRY_INTERVAL_MS = 2_000; // 2 seconds between retries
 
 export async function startStellarLocalnet(): Promise<void> {
     console.log('🚀 Starting Stellar localnet...');
@@ -23,34 +34,87 @@ export async function startStellarLocalnet(): Promise<void> {
     // Start the stellar/quickstart container directly (no Stellar CLI needed)
     await $`docker run -d --name ${CONTAINER_NAME} -p 8086:8000 ${QUICKSTART_IMAGE} --local`;
 
-    // Wait for Stellar to start
-    for (let i = 0; i < 180; i++) {
+    const startTime = Date.now();
+
+    // Wait for RPC to be healthy first (friendbot depends on it)
+    console.log('⏳ Waiting for Stellar RPC to be healthy...');
+    await waitForRpcHealth(startTime);
+    console.log('✅ Stellar RPC is healthy');
+
+    // Wait for friendbot to be ready and fund accounts
+    console.log('⏳ Waiting for friendbot to be ready...');
+    await waitForFriendbotAndFundAccounts(startTime);
+
+    await deployNativeSac();
+    await deployZroToken();
+}
+
+async function waitForRpcHealth(startTime: number): Promise<void> {
+    while (Date.now() - startTime < STARTUP_TIMEOUT_MS) {
         try {
-            // Ensure faucet service is started and fund the default deployer account
-            await fundAccount(DEFAULT_DEPLOYER.publicKey());
-            console.log(`✅ Account ${DEFAULT_DEPLOYER.publicKey()} funded`);
-            await fundAccount(ZRO_DISTRIBUTOR.publicKey());
-            console.log(`✅ Account ${ZRO_DISTRIBUTOR.publicKey()} funded`);
-            await fundAccount(EXECUTOR_ADMIN.publicKey());
-            console.log(`✅ Account ${EXECUTOR_ADMIN.publicKey()} funded`);
-            console.log('✅ Stellar localnet started');
-            break;
-        } catch (_e) {
-            console.error(`❌ Failed to fund account ${_e}`);
-            await sleep(1000);
-            console.log('⏳ Waiting for Stellar localnet to start...');
+            const response = await axios.post(
+                RPC_URL,
+                { jsonrpc: '2.0', id: 1, method: 'getHealth' },
+                {
+                    timeout: REQUEST_TIMEOUT_MS,
+                    headers: { 'Content-Type': 'application/json' },
+                },
+            );
+            if (response.data?.result?.status === 'healthy') {
+                return;
+            }
+        } catch {
+            // RPC not ready yet
         }
+        await sleep(RETRY_INTERVAL_MS);
     }
-    await deployNativeSac();
-    await deployZroToken();
+    throw new Error(
+        `Stellar RPC failed to become healthy within ${STARTUP_TIMEOUT_MS / 1000} seconds`,
+    );
+}
+
+async function waitForFriendbotAndFundAccounts(startTime: number): Promise<void> {
+    const accountsToFund = [
+        { keypair: DEFAULT_DEPLOYER, name: 'DEFAULT_DEPLOYER' },
+        { keypair: ZRO_DISTRIBUTOR, name: 'ZRO_DISTRIBUTOR' },
+        { keypair: EXECUTOR_ADMIN, name: 'EXECUTOR_ADMIN' },
+    ];
+
+    for (const { keypair, name } of accountsToFund) {
+        let funded = false;
+        while (Date.now() - startTime < STARTUP_TIMEOUT_MS) {
+            try {
+                await fundAccount(keypair.publicKey());
+                console.log(`✅ Account ${name} (${keypair.publicKey()}) funded`);
+                funded = true;
+                break;
+            } catch (_error) {
+                const elapsed = Math.round((Date.now() - startTime) / 1000);
+                console.log(`⏳ [${elapsed}s] Waiting for friendbot to fund ${name}...`);
+                await sleep(RETRY_INTERVAL_MS);
+            }
+        }
+        if (!funded) {
+            throw new Error(
+                `Failed to fund account ${name} within ${STARTUP_TIMEOUT_MS / 1000} seconds`,
+            );
+        }
+    }
+    console.log('✅ Stellar localnet started');
 }
 
 export async function fundAccount(publicKey: string): Promise<void> {
-    await axios.get(FRIENDBOT_URL, {
+    const response = await axios.get(FRIENDBOT_URL, {
         params: {
             addr: publicKey,
         },
+        timeout: REQUEST_TIMEOUT_MS,
     });
+
+    // Check for error responses (friendbot returns 400 if already funded, which is OK)
+    if (response.status >= 500) {
+        throw new Error(`Friendbot returned error: ${response.status}`);
+    }
 }
 
 export async function stopStellarLocalnet(): Promise<void> {

package/contracts/ERROR_SPEC.md

@@ -1,51 +0,0 @@
-# Stellar LayerZero Protocol - Error Code Specification
-
-This document defines the error code allocation strategy for the Stellar LayerZero contracts.
-
-## Purpose
-
-Each library has a unique error code range to:
-
-- **Prevent collisions**: Avoid error code conflicts between different libraries
-- **Enable traceability**: Quickly identify which library an error originated from based on its code
-- **Simplify debugging**: Error codes are globally unique, making it easier to track and diagnose issues
-
-## Allocation Rules
-
-- **Library allocation**: Each library is allocated a 100-unit block (e.g., 1000-1099, 1100-1199). Total errors in one library should not exceed 100.
-- **Sub-range allocation**: Each error type within a library is allocated a 10-unit block. Example from `utils` (1000-1099):
-
-    - BufferReaderError: 1000-1009
-    - BufferWriterError: 1010-1019
-    - TtlConfigurableError: 1020-1029
-    - OwnableError: 1030-1039
-    - BytesExtError: 1040-1049
-    - UpgradeableError: 1050-1059
-    - MultisigError: 1060-1069
-
-    Example from `oft/extensions` (3100-3199):
-
-    - OFTFeeError: 3100-3109
-    - OFTPausableError: 3110-3119
-    - RateLimitError: 3120-3129
-
-    If an error type exceeds 10 errors (e.g., 12 errors), it extends into the next block but the following error type should start at the next 10-unit boundary (e.g., if errors are 1000-1011, next sub-range starts at 1020).
-
-- **Auto-increment**: Within each error enum, values auto-increment from the starting value.
-
-## Error Code Ranges
-
-| Range       | Category        | Library            | Description                                                  |
-| ----------- | --------------- | ------------------ | ------------------------------------------------------------ |
-| 1 - 999     | Contract Errors | -                  | Application-specific contract errors (auto-increment from 1) |
-| 1000 - 1099 | Protocol Lib    | utils              | `utils/src/errors.rs`                                        |
-| 1100 - 1199 | Protocol Lib    | message-lib-common | `message-libs/message-lib-common/src/errors.rs`              |
-| 1200 - 1299 | Protocol Lib    | worker             | `workers/worker/src/errors.rs`                               |
-| 1300 - 1999 | Protocol Lib    | (reserved)         | Future protocol libs                                         |
-| 2000 - 2099 | OApp Lib        | oapp               | `oapps/oapp/src/errors.rs`                                   |
-| 2100 - 2999 | OApp Lib        | (reserved)         | Future OApp libs                                             |
-| 3000 - 3099 | OFT Lib         | oft-core           | `oapps/oft-core/src/errors.rs`                               |
-| 3100 - 3199 | OFT Lib         | oft (extensions)   | `oapps/oft/src/extensions/`                                  |
-| 3200 - 3999 | OFT Lib         | (reserved)         | Future OFT libs                                              |
-
----

package/contracts/endpoint-v2/ARCHITECTURE.md

@@ -1,233 +0,0 @@
-# EndpointV2 Architecture
-
-## Overview
-
-**EndpointV2** is the core Soroban contract for LayerZero's cross-chain messaging protocol on Stellar. It serves as the central hub for omnichain applications (OApps) to send and receive cross-chain messages using pluggable message libraries.
-
-**Key Architecture Principles:**
-
-- **Interfaces exported as library** - External contracts depend on trait definitions only
-- **Contract entry point** - `endpoint_v2.rs` implements all interfaces
-- **Internal modules** - Separate files for business logic implementation
-- **Centralized resources** - Unified `storage.rs`, `errors.rs`, `events.rs`
-
----
-
-## Project Structure
-
-```
-endpoint-v2/
-├── Cargo.toml                      # Package configuration with "library" feature
-├── ARCHITECTURE.md                 # This file - architecture documentation
-│
-├── src/
-
-│   ├── interfaces/                 # Public interface definitions (library exports)
-│   │   ├── mod.rs
-│   │   ├── layerzero_endpoint_v2.rs      # Core endpoint interface
-│   │   ├── layerzero_composer.rs         # Interface for Composer
-│   │   ├── layerzero_receiver.rs         # Interface for OApp (receive)
-│   │   ├── message_lib.rs                # Interface for MessageLib
-│   │   ├── message_lib_manager.rs        # Library management interface of EndpointV2
-│   │   ├── send_lib.rs                   # Interface for SendLib (extends MessageLib)
-│   │   ├── messaging_channel.rs          # Channel operations interface of EndpointV2
-│   │   └── messaging_composer.rs         # Compose operations interface of EndpointV2
-|   |
-│   ├── lib.rs                      # Module exports & conditional compilation
-│   ├── endpoint_v2.rs              # Main contract implementation
-│   ├── message_lib_manager.rs      # Internal: Library registration & management
-│   ├── messaging_channel.rs        # Internal: Channel logic (nonce, payload)
-│   ├── messaging_composer.rs       # Internal: Compose queue management
-│   │
-│   ├── util.rs                     # Public: Utility functions (GUID, payload, keccak256)
-│   ├── storage.rs                  # Centralized storage management
-│   ├── errors.rs                   # Centralized error definitions
-│   ├── events.rs                   # Centralized event definitions
-│   │
-│   └── tests/                      # Comprehensive test suite
-
-```
-
----
-
-## Design Principles
-
-### 1. Interfaces as Library Exports
-
-The `interfaces/` directory contains Soroban trait definitions exported as a library for external contracts. Controlled by the `library` feature in `Cargo.toml`.
-
-```rust
-// lib.rs - conditional compilation
-cfg_if::cfg_if! {
-    if #[cfg(any(not(feature = "library"), feature = "default"))] {
-        mod endpoint_v2;  // Only included when building contract
-        mod errors;
-        mod events;
-        mod storage;
-
-        pub use endpoint_v2::{EndpointV2, EndpointV2Client};
-    }
-}
-```
-
-**Usage Example:**
-
-```rust
-// In a MessageLib contract
-use endpoint_v2::{EndpointV2Client, OutboundPacket};
-
-let endpoint = EndpointV2Client::new(&env, &endpoint_address);
-endpoint.verify(&origin, &receiver, &payload_hash);
-```
-
-**Interface Categories:**
-
-- **For OApps**: `ILayerZeroReceiver`, `ILayerZeroComposer`
-- **For MessageLibs**: `IMessageLib`, `ISendLib` (includes `OutboundPacket`, `FeeRecipient`)
-- **For All**: `ILayerZeroEndpointV2` (composes all sub-interfaces)
-- **Utilities**: `util::compute_guid()`, `util::build_payload()`, `util::keccak256()`
-
-### 2. Contract Entry Point (`endpoint_v2.rs`)
-
-The main Soroban contract that implements all interfaces and delegates to internal modules:
-
-```rust
-#[contract]
-pub struct EndpointV2;
-
-#[contract_impl]
-impl EndpointV2 {
-    pub fn __constructor(env: &Env, eid: u32, native_token: &Address, owner: &Address) {
-        storage::EndpointData::set_eid(env, eid);
-        storage::EndpointData::set_native_token(env, native_token);
-        ownable::set_owner(env, owner);
-    }
-
-    pub fn set_ttl_configs(env: &Env, ...) {
-        ownable::require_owner_auth(env);
-        // Configure TTL settings for storage
-    }
-}
-
-#[contract_impl]
-impl ILayerZeroEndpointV2 for EndpointV2 {
-    fn send(env: &Env, sender: &Address, params: &MessagingParams, ...) -> MessagingReceipt {
-        sender.require_auth();
-        // Send cross-chain message via SendLib
-    }
-
-    fn lz_receive(env: &Env, origin: &Origin, receiver: &Address, ...) {
-        // Verify payload hash and deliver to OApp
-        let receiver_client = LayerZeroReceiverClient::new(env, receiver);
-        receiver_client.lz_receive(...);
-    }
-}
-
-#[contract_impl]
-impl Ownable for EndpointV2 {
-    // Ownership management
-}
-```
-
-**Implements:** `ILayerZeroEndpointV2` (which includes `IMessageLibManager`, `IMessagingChannel`, `IMessagingComposer`), `Ownable`
-
-### 3. Internal Implementation Modules
-
-Internal modules provide business logic implementation for `endpoint_v2.rs`:
-
-| Module                       | Purpose                                                                                                  |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
-| **`message_lib_manager.rs`** | Library registration, selection, and configuration. Tracks default/per-OApp libraries per EID.           |
-| **`messaging_channel.rs`**   | Nonce tracking, payload hash storage/verification, message state transitions (verify → receive → clear). |
-| **`messaging_composer.rs`**  | Manages compose message queues for multi-stage execution between OApp and Composers.                     |
-| **`util.rs`**                | Public utilities: `compute_guid()`, `build_payload()`, `keccak256()` for message processing.             |
-
-### 4. Centralized Resource Management
-
-| Module           | Purpose                                                                                                                                                     | Example                                                                                          |
-| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| **`storage.rs`** | Type-safe storage with `#[storage]` derive macro. Organized into: `EndpointData`, `MessagingChannelData`, `MessageLibManagerData`, `MessagingComposerData`. | `EndpointData::eid(env)`, `MessagingChannelData::outbound_nonce(env, sender, dst_eid, receiver)` |
-| **`errors.rs`**  | All error codes using `#[contracterror]`. 29 error types including validation, authorization, state, and configuration errors.                              | `InvalidNonce = 3`, `Unauthorized = 10`, `InsufficientNativeFee = 27`                            |
-| **`events.rs`**  | All events using `#[contractevent]`. Includes config, messaging, library, and compose events.                                                               | `PacketSent`, `PacketVerified`, `LibraryRegistered`                                              |
-
----
-
-## Key Patterns
-
-**1. Interface Composition**
-
-```rust
-pub trait ILayerZeroEndpointV2:
-    IMessageLibManager + IMessagingChannel + IMessagingComposer
-{
-    fn quote(env: &Env, sender: &Address, params: &MessagingParams) -> MessagingFee;
-    fn send(env: &Env, sender: &Address, params: &MessagingParams, refund_address: &Address) -> MessagingReceipt;
-    fn lz_receive(env: &Env, origin: &Origin, receiver: &Address, guid: &BytesN<32>, message: &Bytes, extra_data: &Bytes);
-    // ... more methods
-}
-```
-
-Each sub-interface handles one domain, enabling modularity and clear separation of concerns. Ownership is handled through the `Ownable` trait from the `utils` crate.
-
-**2. Client Generation**
-
-```rust
-#[contractclient(name = "LayerZeroReceiverClient")]
-pub trait ILayerZeroReceiver {
-    fn lz_receive(env: &Env, origin: &Origin, guid: &BytesN<32>, message: &Bytes, extra_data: &Bytes);
-}
-
-// Usage: type-safe cross-contract calls
-let receiver = LayerZeroReceiverClient::new(&env, &receiver_address);
-receiver.lz_receive(&origin, &guid, &message, &extra_data);
-```
-
-The `#[contractclient]` macro automatically generates type-safe client wrappers for cross-contract calls.
-
----
-
-## Message Flows
-
-### Sending
-
-```
-OApp → EndpointV2.send(sender, params, refund_address)
-    ↓
-    MessageLibManager.get_send_library(sender, dst_eid)
-    ↓
-    MessagingChannel.outbound_nonce++ (create OutboundPacket)
-    ↓
-    SendLib.send(packet, options, pay_in_zro) → Returns (Vec<FeeRecipient>, encoded_packet)
-    ↓
-    Pay fees (native or ZRO) to fee recipients
-    ↓
-    Emit PacketSent event
-    ↓
-    Return MessagingReceipt { guid, nonce, fee }
-```
-
-### Receiving
-
-```
-Off-chain Verifier → EndpointV2.verify(origin, receiver, payload_hash)
-    ↓
-    Validate library is registered receive lib
-    ↓
-    MessagingChannel.inbound(receiver, origin, payload_hash) → Store payload hash
-    ↓
-    Emit PacketVerified event
-
-Later: Executor → OApp.lz_receive(origin, guid, message, extra_data)
-    ↓
-    OApp executes business logic
-    ↓
-    OApp → EndpointV2.clear(caller, origin, receiver, guid, message)
-    ↓
-    Validate caller is OApp or its delegate (require_oapp_auth)
-    ↓
-    Validate payload hash matches keccak256(guid || message)
-    ↓
-    Clear payload hash from storage
-    ↓
-    Emit PacketDelivered event
-```