@layerzerolabs/oapp-solana-contracts 1.2.11

package/Anchor.toml

@@ -0,0 +1,23 @@
+[toolchain]
+anchor_version = "1.0.2"
+solana_version = "3.1.10"
+
+[features]
+seeds = false
+skip-lint = false
+resolution = false
+
+[programs.localnet]
+counter = "Cnt11111111111111111111111111111111111111111"
+
+[registry]
+url = "https://api.apr.dev"
+
+[provider]
+cluster = "Localnet"
+wallet = "~/.config/solana/id.json"
+
+[workspace]
+members = [
+    "macros/examples/counter",
+]

package/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "oapp"
+version = "0.1.0"
+edition = "2021"
+
+[features]
+default = []
+idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build", "oapp-macros/idl-build"]
+
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(target_os, values("solana"))'] }
+
+[dependencies]
+anchor-lang = { version = "1.0.2" }
+anchor-spl = { version = "1.0.2" }
+oapp-macros = { path = "macros" }
+solana-address-lookup-table-interface = { version = "3.0.1", features = [
+    "bincode",
+    "bytemuck",
+] }
+solana-keccak-hasher = "3.1.0"
+spl-type-length-value = { version = "0.9.1", features = ["derive"] }
+spl-discriminator = "0.5.2"
+
+[profile.release]
+overflow-checks = true

package/README.md

@@ -0,0 +1,181 @@
+# OApp Standard
+
+## Overview
+
+The OApp Standard for Solana is a unified framework that standardizes how OApp programs expose instructions, how SDKs interact with them, and how account discovery is performed.
+
+The standard consists of two parts:
+
+1. **OApp Interface Standard** — a formal instruction interface (`OAppInstructionSet`) that every OApp program must implement.
+2. **OApp Info** — a program-level on-chain metadata PDA (`OAppInfo`) that enables the SDK to resolve accounts for each instruction.
+
+The appendices document the existing **LzReceiveTypes** and **LzComposeTypes**
+protocols. LzReceiveTypes handles account discovery for `lz_receive` — the one
+OApp instruction not covered by `OAppInfo`; LzComposeTypes handles the follow-up
+compose execution on composer programs.
+
+| Component               | Detailed Spec                                       |
+| ----------------------- | --------------------------------------------------- |
+| OApp Interface Standard | [`oapp-macro.md`](./docs/oapp-macro.md)             |
+| OApp Info               | [`oapp-info.md`](./docs/oapp-info.md)               |
+| LzReceiveTypes          | [`lz-receive-types.md`](./docs/lz-receive-types.md) |
+| LzComposeTypes          | [`lz-compose-types.md`](./docs/lz-compose-types.md) |
+
+> **Operators:** if you run your own Executor, read
+> [`running-an-executor.md`](./docs/running-an-executor.md). The Executor signing keypair must
+> hold nothing but SOL — this applies to both `lz_receive` and `lz_compose` execution.
+
+---
+
+## Motivation
+
+### No Standard Interface
+
+The original OApp design had no standard interface. There was no definition of what instructions an OApp must expose, so each OApp was built differently and SDKs had to be written per-app.
+
+Beyond the lack of standardization, the SDK read on-chain state by directly decoding PDA account bytes rather than calling view functions. This tightly coupled the SDK to the binary layout of each account struct — any structural change required a synchronized SDK update, and a single SDK could not support multiple deployed versions simultaneously. On other VMs, this problem does not exist because state is always accessed through stable function interfaces.
+
+The OApp Standard addresses this by defining a formal instruction interface via `anchor-trait` (`OAppInstructionSet`), including view functions for all state-reading operations. The SDK now interacts with on-chain state through these interfaces, decoupled from underlying struct layouts.
+
+### No Account Discovery
+
+A standard interface tells the SDK _what_ to call, but not _how_ to call it. On Solana, every account must be declared upfront in the transaction. The SDK cannot construct a complete instruction without knowing the exact set of accounts — including PDAs, signers, and program references — for each instruction it wants to invoke.
+
+In the old design there was no standard mechanism for this. The SDK hardcoded account lists per OApp type, which broke whenever account layouts changed between deployments.
+
+Even with `OAppInstructionSet` standardizing the interface, account resolution still requires additional information: which version of the standard does this program implement, and what accounts does that version use? This program-level metadata is what `OAppInfo` provides.
+
+---
+
+## OApp Interface Standard
+
+Every OApp program exposes a standard set of instructions, generated by the `#[oapp]` and `#[rbac]` attribute macros. The SDK interacts with all of these instructions uniformly.
+
+### OApp Instructions
+
+Generated by the `#[oapp]` attribute macro from `oapp`.
+
+| Instruction             | View | Has Default | Description                                                |
+| ----------------------- | ---- | ----------- | ---------------------------------------------------------- |
+| `set_peer`              | No   | Yes         | Register a trusted remote OApp                             |
+| `get_peer`              | Yes  | Yes         | Read registered peer address                               |
+| `init_enforced_options` | No   | Yes         | Create the EnforcedOptions PDA with initial options buffer |
+| `set_enforced_options`  | No   | Yes         | Update enforced send options (with resize)                 |
+| `get_enforced_options`  | Yes  | Yes         | Read enforced options                                      |
+| `next_nonce`            | Yes  | Yes         | Read next inbound nonce                                    |
+| `is_compose_msg_sender` | Yes  | Yes         | Validate compose message sender                            |
+| `lz_receive_types_info` | Yes  | No          | Return LzReceiveTypes version and accounts                 |
+| `lz_receive_types_v2`   | Yes  | No          | Return accounts and instructions for lz_receive            |
+| `lz_receive`            | No   | No          | Execute inbound cross-chain message                        |
+
+### RBAC Instructions
+
+Generated by the `#[rbac]` attribute macro from `rbac`. All have default implementations.
+
+| Instruction                     | Description                                                 |
+| ------------------------------- | ----------------------------------------------------------- |
+| `begin_default_admin_transfer`  | Initiate two-step admin transfer                            |
+| `accept_default_admin_transfer` | New admin accepts the transfer                              |
+| `grant_role`                    | Grant a role to an account                                  |
+| `revoke_role`                   | Revoke a role from an account                               |
+| `renounce_role`                 | Voluntarily renounce own role                               |
+| `get_default_admin`             | View current and pending default admin (`DefaultAdminInfo`) |
+
+> **Note:** Under `#[oapp]`, `accept_default_admin_transfer` is unconditionally overridden with an OApp-specific handler that completes the RBAC admin transfer and then CPIs `set_delegate` on the endpoint — keeping the endpoint delegate in sync with the new admin (EVM parity with `OAppCoreRBACUpgradeable`). Programs cannot override this behavior via `#[oapp_instruction]`.
+>
+> **Security Note (`lz_receive`):** The Endpoint does NOT validate the inbound peer. The `lz_receive` override MUST bind an `OAppPeer` PDA to `params.src_eid` via `seeds` and enforce `peer.address == params.sender` — recommended declaratively via Anchor's `constraint`. Omitting this check lets any program impersonate a registered peer. See the `#[oapp_instruction]` rustdoc for the canonical Anchor account snippet.
+
+### Initialization Requirements
+
+The `#[oapp]` macro generates instruction entrypoints, but deployment initialization remains the program's responsibility. A production OApp `initialize` handler must complete these setup steps:
+
+| Setup item        | Call                                    | Purpose                                                                      |
+| ----------------- | --------------------------------------- | ---------------------------------------------------------------------------- |
+| RBAC admin state  | `setup_default_admin!`                  | Initializes the first default admin and RoleMember PDA.                      |
+| OApp metadata     | `init_oapp_base!` / app-specific helper | Writes OAppInfo metadata used by the SDK for account discovery.              |
+| Endpoint registry | `endpoint_cpi::register_oapp(...)`      | Creates the endpoint registry entry used by delegate sync and endpoint CPIs. |
+
+The table order is the recommended initialization order. `OAppInfo` is initialized by the application, not generated by `#[oapp]`, because account sizing and app-layer TLV entries are program-specific. Programs that want shared SDK discovery should create and populate this PDA during initialization; programs that intentionally omit it are outside the standardized discovery path. Before revoking upgrade authority, confirm the intended `OAppInfo` metadata is present.
+
+Missing `register_oapp` makes the OApp-specific `accept_default_admin_transfer` handler's `set_delegate` CPI fail, which can permanently brick admin transfers.
+
+### Column Definitions
+
+- **Has Default = Yes** — the macro auto-generates a complete context struct and handler. OApp developers get correct behavior without writing any code for these instructions.
+- **Has Default = No** — a required override. The developer must provide a handler via `#[oapp_instruction]`. Omitting it is a compile error.
+- **View = Yes** — the instruction uses an immutable context and returns a value. The SDK calls these to read on-chain state without submitting a transaction.
+
+### The `#[oapp]` Macro
+
+The `#[oapp]` attribute macro wires an OApp program module into `OAppInstructionSet`. It generates default context structs and entrypoints for all instructions where a default exists, applies RBAC enforcement on admin instructions, and enforces that all required overrides are provided at compile time.
+
+For the full macro API, override model (Default / Override), and generated code details, see [`oapp-macro.md`](./docs/oapp-macro.md).
+
+### Implementation Notes
+
+#### PDA Seed Helpers
+
+Anchor 1.0.0 relaxed `#[account(seeds = ...)]` parsing to support more flexible PDA seed expressions, including helper calls. OApp programs should use canonical seed helper functions for non-trivial PDA shapes instead of repeating inline byte conversions in every account constraint.
+
+```rust
+#[account(
+    seeds = OAppPeer::seeds(&oapp.key(), params.eid),
+    bump = peer.bump
+)]
+pub peer: Account<'info, OAppPeer>,
+```
+
+The helper owns the exact seed layout and byte encoding:
+
+```rust
+pub fn lz_receive_types_seeds(oapp_key: &Pubkey) -> &'static [&'static [u8]] {
+    let key_bytes: &'static [u8; 32] = Box::leak(Box::new(oapp_key.to_bytes()));
+    Box::leak(Box::new([LZ_RECEIVE_TYPES_SEED, key_bytes.as_slice()]))
+}
+```
+
+This pattern keeps account constraints readable and makes PDA layouts discoverable in one place. The `Box::leak` form is SVM-only: each invocation leaks a small allocation, which is acceptable inside an on-chain instruction because the VM allocator is discarded at the end of the transaction. Do not use these helpers from long-running off-chain Rust processes such as native test runners, indexers, or CLIs; derive those PDAs with stack-local byte arrays instead.
+
+---
+
+## OApp Info
+
+Even with a standardized interface, the SDK needs per-program metadata to construct complete transactions. `OAppInfo` is a versioned, extensible PDA that each OApp program may publish on-chain for standardized SDK discovery, giving the SDK everything it needs in a single read.
+
+Key concepts:
+
+- **`OAppInfo` PDA** — one per program, derived from `[OAPP_INFO_SEED]` (`find_program_address` already namespaces the result to the calling program). Stores raw SPL TLV entries from byte 0 (no Anchor discriminator); each framework layer appends its own typed entry as a sibling.
+- **`OAppBase` entry** — always written first. Carries two orthogonal version axes — `schema_version` (Borsh layout of the entry) and `idl_version` (`{ major, minor }` covering the OApp instruction set and emitted events) — plus an `app_discriminator` pointing to the optional app-layer sibling entry.
+- **`lz_receive` excluded** — no default implementation; account discovery is delegated entirely to the LzReceiveTypes protocol.
+
+For the full `OAppInfo` struct, SDK decision flow, app-specific extensions, and the relationship with LzReceiveTypes, see [`oapp-info.md`](./docs/oapp-info.md).
+
+---
+
+## Appendix: LzReceiveTypes
+
+> LzReceiveTypes is an existing protocol that predates the OApp Standard. It is documented here for completeness, as it handles account discovery for `lz_receive` — the one instruction not covered by `OAppInfo`.
+
+`lz_receive` is unique among OApp instructions: its accounts depend on the message content and cannot be resolved off-chain from a predefined template. The LzReceiveTypes protocol solves this by providing an on-chain instruction (`lz_receive_types_v2`) that returns the exact accounts and instructions needed for a given message.
+
+Key concepts:
+
+- **Two-stage execution** — the Executor first calls `lz_receive_types_v2` to discover accounts, then submits the full `lz_receive` transaction.
+- **Transaction-based model (V2)** — replaces the original CPI-based model to avoid Solana's CPI depth limit of 4, enabling ABA messaging patterns.
+- **`AddressLocator` enum** — compact account referencing via direct address, ALT index, payer, additional signers, or executor context account.
+- **Multi-instruction support** — `lz_receive_types_v2` can return multiple instructions (preprocessing steps + `lz_receive`), executed atomically in a single transaction.
+- **Versioned via `lz_receive_types_info`** — the protocol self-describes its version; the Executor reads this to determine how to interact with the OApp.
+
+For the full protocol design, data structures, execution flow, and V2 transaction model, see [`lz-receive-types.md`](./docs/lz-receive-types.md).
+
+---
+
+## Appendix: LzComposeTypes
+
+`lz_compose` is the follow-up execution phase for composed messages emitted by
+`lz_receive`. LzComposeTypes uses the same V2 account reference and transaction
+model as LzReceiveTypes, but its interface is scoped to composer programs and
+`LzComposeParams`.
+
+For the compose-specific interface and differences, see
+[`lz-compose-types.md`](./docs/lz-compose-types.md).