DVN and Executor Configuration on Stellar

This guide covers how to configure the security and execution stack for your LayerZero OApp or OFT on Stellar.

Overview

Configuring a LayerZero application on Stellar involves these steps:

Configure DVN — set verification parameters (required DVNs, optional DVNs, confirmations)
Configure Executor — set execution parameters (max message size, executor address)
Set Enforced Options — define minimum execution options per destination

DVN Configuration

DVNs (Decentralized Verifier Networks) verify crosschain messages. Configuration is done via the ULN-302 message library through the endpoint’s set_config function.

ULN Config Structure

struct UlnConfig {
    confirmations: u64,           // Block confirmations required
    required_dvns: Vec<Address>,  // DVNs that MUST ALL verify
    optional_dvns: Vec<Address>,  // Pool of optional DVNs
    optional_dvn_threshold: u32,  // How many optional DVNs must verify
}

Field	Description	Default Behavior
`confirmations`	Source chain block confirmations before DVN verification	Uses default if `use_default_confirmations = true`
`required_dvns`	All listed DVNs must verify every message	Uses default if `use_default_required_dvns = true`
`optional_dvns`	Pool of additional DVNs	Uses default if `use_default_optional_dvns = true`
`optional_dvn_threshold`	Minimum optional DVNs that must verify	Must be ≤ `optional_dvns.len()`

The effective config must have at least one DVN — either required_dvns must be non-empty, or optional_dvn_threshold must be greater than 0.

Configure Send DVN

Set the DVN configuration for outbound messages:

stellar contract invoke \
  --id <ENDPOINT_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  set_config \
  --caller <DELEGATE_ADDRESS> \
  --oapp <YOUR_OAPP_ADDRESS> \
  --lib <ULN302_ADDRESS> \
  --params '[{"eid": <DST_EID>, "config_type": 2, "config": "<XDR_ENCODED_SEND_ULN_CONFIG>"}]'

Config type 2 = CONFIG_TYPE_SEND_ULN.

Configure Receive DVN

Set the DVN configuration for inbound messages:

stellar contract invoke \
  --id <ENDPOINT_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  set_config \
  --caller <DELEGATE_ADDRESS> \
  --oapp <YOUR_OAPP_ADDRESS> \
  --lib <ULN302_ADDRESS> \
  --params '[{"eid": <SRC_EID>, "config_type": 3, "config": "<XDR_ENCODED_RECEIVE_ULN_CONFIG>"}]'

Config type 3 = CONFIG_TYPE_RECEIVE_ULN.

OApp ULN Config

When setting per-OApp config, use OAppUlnConfig which includes flags to fall back to defaults:

struct OAppUlnConfig {
    use_default_confirmations: bool,
    use_default_required_dvns: bool,
    use_default_optional_dvns: bool,
    uln_config: UlnConfig,
}

Set a field’s use_default_* flag to true to inherit the network-wide default for that field, even if you customize other fields.

When a use_default_* flag is true, the corresponding config values must be zero or empty. For example, if use_default_confirmations is true, confirmations must be 0. If use_default_required_dvns is true, required_dvns must be empty. Violating this constraint will cause the transaction to fail.

Executor Configuration

The Executor delivers verified messages to the destination OApp. Configuration is also done via set_config:

struct OAppExecutorConfig {
    max_message_size: u32,      // 0 = use default
    executor: Option<Address>,  // None = use default
}

stellar contract invoke \
  --id <ENDPOINT_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  set_config \
  --caller <DELEGATE_ADDRESS> \
  --oapp <YOUR_OAPP_ADDRESS> \
  --lib <ULN302_ADDRESS> \
  --params '[{"eid": <DST_EID>, "config_type": 1, "config": "<XDR_ENCODED_EXECUTOR_CONFIG>"}]'

Config type 1 = CONFIG_TYPE_EXECUTOR.

The config field in SetConfigParam is XDR-encoded bytes. Soroban contract types (OAppUlnConfig, OAppExecutorConfig) must be serialized to XDR before passing to set_config. Use the Stellar SDK’s toXDR() method or the stellar-xdr Rust crate to encode these structs.

Setting Enforced Options

Enforced options define the minimum execution parameters for outbound messages. They are combined with any caller-provided options:

stellar contract invoke \
  --id <YOUR_OAPP_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  set_enforced_options \
  --options '[{"eid": <DST_EID>, "msg_type": 1, "options": "<OPTIONS_HEX>"}]' \
  --operator <OWNER_ADDRESS>

The options field is Option<Bytes> — pass null to remove enforced options for a given eid/msg_type combination.

Message Type	Description
`1`	`SEND` — standard message (OFT: token transfer)
`2`	`SEND_AND_CALL` — message with compose (OFT: token transfer + compose)

Always set enforced options for each destination. Without them, messages may fail due to insufficient gas on the destination chain. For SEND_AND_CALL (type 2), ensure the gas limit accounts for the compose execution.

Gas Options Example

When setting enforced options or passing extra_options in a send, you must specify the gas for lzReceive on the destination chain. The following examples use the standard LayerZero Type 3 encoding:

Operation	Example Gas	Options Hex
Basic `lz_receive` (OFT transfer)	200,000	`00030100110100000000000000000000000000030d40`
`lz_receive` + `lz_compose`	500,000	`0003010011010000000000000000000000000007a120`

The options format is: 0x0003 (Type 3 header) + 01 (executor worker ID) + 0011 (length = 17 bytes) + 01 (lzReceive option type) + gas as uint128.

Sending with empty extra_options and no enforced options will cause the send to fail with error #1114 at the message library level. Always include executor options specifying the gas for lzReceive on the destination.

Reading Configuration

Query the current configuration for your OApp:

# Get effective send ULN config
stellar contract invoke \
  --id <ULN302_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  effective_send_uln_config \
  --sender <YOUR_OAPP_ADDRESS> \
  --dst_eid <DESTINATION_EID>

# Get effective receive ULN config
stellar contract invoke \
  --id <ULN302_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  effective_receive_uln_config \
  --receiver <YOUR_OAPP_ADDRESS> \
  --src_eid <SOURCE_EID>

# Get effective executor config
stellar contract invoke \
  --id <ULN302_ADDRESS> \
  --network testnet \
  --source my-account \
  -- \
  effective_executor_config \
  --sender <YOUR_OAPP_ADDRESS> \
  --dst_eid <DESTINATION_EID>

Next Steps

Technical Overview: Understand how DVN verification and executor delivery work end-to-end.
Troubleshooting: Common configuration errors and solutions.

LayerZero for Stellar

Contract Standards

Technical Reference

Troubleshooting

Resources

DVN and Executor Configuration on Stellar

Overview

DVN Configuration

ULN Config Structure

Configure Send DVN

Configure Receive DVN

OApp ULN Config

Executor Configuration

Setting Enforced Options

Gas Options Example

Reading Configuration

Next Steps

​Overview

​DVN Configuration

​ULN Config Structure

​Configure Send DVN

​Configure Receive DVN

​OApp ULN Config

​Executor Configuration

​Setting Enforced Options

​Gas Options Example

​Reading Configuration

​Next Steps

Overview

DVN Configuration

ULN Config Structure

Configure Send DVN

Configure Receive DVN

OApp ULN Config

Executor Configuration

Setting Enforced Options

Gas Options Example

Reading Configuration

Next Steps