@layerzerolabs/oapp-solana-contracts 1.2.62 → 1.2.64

package/src/common.rs

@@ -1,9 +1,4 @@
-use std::collections::HashMap;
-
 use anchor_lang::{prelude::*, Discriminator};
-use solana_address_lookup_table_interface::state::AddressLookupTable;
-
-use crate::errors::OAppError;
 
 pub const EXECUTION_CONTEXT_SEED: &[u8] = b"ExecutionContext";
 pub const EXECUTION_CONTEXT_VERSION_1: u8 = 1;
@@ -47,110 +42,33 @@ impl anchor_lang::AccountDeserialize for ExecutionContextV1 {
     }
 }
 
-/// A generic account locator used in LZ execution planning for V2.
-/// Can reference the address directly, via ALT, or as a placeholder.
+/// How a planned instruction names an account; the Executor resolves it when building delivery.
 ///
-/// This enum enables the compact account referencing design of V2, supporting:
-/// - OApps to request multiple signer accounts, not just a single Executor EOA
-/// - Dynamic creation of writable EOA-based data accounts
-/// - Efficient encoding of addresses via ALTs, reducing account list size
-///
-/// The legacy is_signer flag is removed. Instead, signer roles are explicitly
-/// declared through Payer and indexed Signer(u8) variants.
-#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+/// Only `Payer` and `Signer` resolve to signers, so a literal `Address` can never request a
+/// signature.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug, PartialEq, Eq)]
 pub enum AddressLocator {
-    /// Directly supplied public key - standard address reference
+    /// A literal account address.
     Address(Pubkey),
-    /// Indexed address from a specific Address Lookup Table (ALT)
-    /// Format: (ALT list index, address index within ALT)
-    /// Enables efficient account list compression via Solana's ALT mechanism
-    AltIndex(u8, u8),
-    /// Executor's fee payer - substituted by the Executor's EOA
-    /// This is the primary signer and fee payer for the transaction
+    /// The Executor's fee payer.
     Payer,
-    /// Additional signer accounts - substituted by EOAs provided by the Executor
-    /// The u8 index identifies each signer's position in the signer list,
-    /// allowing the OApp to reference multiple distinct signers for dynamic account creation
+    /// An additional Executor-provided signer, e.g. the keypair of an account the plan creates.
+    /// Equal indices refer to the same key throughout the plan.
     Signer(u8),
-    /// A context account provided by the Executor containing execution
-    /// metadata, such as SOL spend limits.
+    /// The Executor's execution-context PDA (`[EXECUTION_CONTEXT_SEED, payer, context_version]`
+    /// under the Executor program), e.g. an [`ExecutionContextV1`].
     Context,
-    // Append more address placeholders in the future.
 }
 
 impl From<Pubkey> for AddressLocator {
-    fn from(pubkey: Pubkey) -> Self {
-        AddressLocator::Address(pubkey)
+    fn from(key: Pubkey) -> Self {
+        Self::Address(key)
     }
 }
 
-/// Account metadata for V2 execution planning.
-/// Used by the Executor to construct the final transaction.
-///
-/// V2 removes the legacy is_signer flag from V1's AccountMeta.
-/// Instead, signer roles are explicitly declared through AddressLocator variants.
-/// This provides clearer semantics and enables multiple signer support.
-#[derive(AnchorSerialize, AnchorDeserialize, Clone)]
+/// One account of a planned instruction. Signer status comes from the locator, not a flag.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug, PartialEq, Eq)]
 pub struct AccountMetaRef {
-    /// The account address locator - supports multiple resolution strategies
     pub pubkey: AddressLocator,
-    /// Whether the account should be writable in the final transaction
     pub is_writable: bool,
 }
-
-pub fn compact_accounts_with_alts(
-    alt_accounts: &[AccountInfo],
-    instruction_accounts: Vec<AccountMetaRef>,
-) -> Result<Vec<AccountMetaRef>> {
-    // Build address lookup table mapping from remaining_accounts
-    // This enables efficient account referencing via ALT indices
-    let address_to_alt_index_map = build_address_to_alt_index_map(alt_accounts)?;
-
-    // Convert accounts to use ALT indices where possible
-    let compacted_accounts = instruction_accounts
-        .into_iter()
-        .map(|mut account_meta| {
-            if let AddressLocator::Address(pubkey) = account_meta.pubkey {
-                account_meta.pubkey = to_address_locator(&address_to_alt_index_map, pubkey);
-            }
-            account_meta
-        })
-        .collect();
-
-    Ok(compacted_accounts)
-}
-
-pub fn to_address_locator(
-    address_to_alt_index_map: &HashMap<Pubkey, (u8, u8)>,
-    key: Pubkey,
-) -> AddressLocator {
-    address_to_alt_index_map
-        .get(&key)
-        .map(|alt_index| AddressLocator::AltIndex(alt_index.0, alt_index.1))
-        .unwrap_or(AddressLocator::Address(key))
-}
-
-/// Helper function to deserialize AddressLookupTable data
-pub fn deserialize_alt(alt: &AccountInfo) -> Result<Vec<Pubkey>> {
-    let data = alt
-        .try_borrow_data()
-        .map_err(|_| error!(OAppError::InvalidAddressLookupTable))?;
-    AddressLookupTable::deserialize(*data)
-        .map(|alt| alt.addresses.to_vec())
-        .map_err(|_| error!(OAppError::InvalidAddressLookupTable))
-}
-
-/// Helper function to build a map of addresses to their ALT indices
-pub fn build_address_to_alt_index_map(
-    alt_accounts: &[AccountInfo],
-) -> Result<HashMap<Pubkey, (u8, u8)>> {
-    let mut address_to_alt_index_map: HashMap<Pubkey, (u8, u8)> = HashMap::new();
-    for (alt_index, alt) in alt_accounts.iter().enumerate() {
-        let addresses_in_alt = deserialize_alt(alt)?;
-        for (address_index_in_alt, address_in_alt) in addresses_in_alt.iter().enumerate() {
-            address_to_alt_index_map
-                .insert(*address_in_alt, (alt_index as u8, address_index_in_alt as u8));
-        }
-    }
-    Ok(address_to_alt_index_map)
-}

package/src/endpoint_cpi.rs

@@ -22,10 +22,14 @@
 
 use crate::endpoint::{
     self,
-    cpi::accounts::{Clear, ClearCompose, Quote, RegisterOapp, Send, SendCompose, SetDelegate},
+    cpi::accounts::{
+        Burn, Clear, ClearCompose, Nilify, Quote, RegisterOapp, Send, SendCompose, SetDelegate,
+        Skip,
+    },
     types::{
-        ClearComposeParams, ClearParams, MessagingFee, MessagingReceipt, QuoteParams,
-        RegisterOAppParams, SendComposeParams, SendParams, SetDelegateParams,
+        BurnParams, ClearComposeParams, ClearParams, MessagingFee, MessagingReceipt, NilifyParams,
+        QuoteParams, RegisterOAppParams, SendComposeParams, SendParams, SetDelegateParams,
+        SkipParams,
     },
 };
 use anchor_lang::{
@@ -41,6 +45,9 @@ pub const QUOTE_MIN_ACCOUNTS_LEN: usize = 7;
 pub const CLEAR_MIN_ACCOUNTS_LEN: usize = 8;
 pub const SEND_COMPOSE_MIN_ACCOUNTS_LEN: usize = 7;
 pub const CLEAR_COMPOSE_MIN_ACCOUNTS_LEN: usize = 5;
+pub const SKIP_MIN_ACCOUNTS_LEN: usize = 9;
+pub const BURN_MIN_ACCOUNTS_LEN: usize = 8;
+pub const NILIFY_MIN_ACCOUNTS_LEN: usize = 8;
 
 fn validate(accounts: &[AccountInfo], endpoint_program: Pubkey, min_len: usize) -> Result<()> {
     require!(accounts.len() >= min_len, ErrorCode::AccountNotEnoughKeys);
@@ -249,9 +256,9 @@ pub fn quote(
 
 /// Marks an inbound message as received by clearing it from the Endpoint.
 ///
-/// Called during `lz_receive` processing to acknowledge that the OApp has consumed the
-/// message payload for a given (srcEid, sender, nonce) tuple. This advances the
-/// inbound nonce and allows subsequent messages to be delivered.
+/// Called during `lz_receive` processing to validate and consume the verified payload for a
+/// given (srcEid, sender, nonce) tuple. The inbound nonce must already cover this message;
+/// clearing the payload does not advance it.
 ///
 /// # Accounts layout
 /// The `accounts` slice must follow the `Clear` struct field order:
@@ -268,9 +275,8 @@ pub fn quote(
 ///
 /// # Accounts validation
 /// - `accounts[0]` must equal the caller-supplied `endpoint_program` parameter.
-/// - `accounts[1]` is the `signer` — pinned to `receiver`. The OApp PDA path signs via `seeds`; the
-///   delegate path requires the delegate to already be a signer. The Endpoint accepts either the
-///   OApp PDA (`params.receiver`) or the registered delegate as `signer`.
+/// - `accounts[1]` is the `signer` — pinned to `receiver`, as is `params.receiver`, so the
+///   Endpoint's delegate-signer path is not available through this wrapper.
 ///
 /// # Returns
 /// The payload hash (`[u8; 32]`) of the cleared message.
@@ -283,6 +289,7 @@ pub fn clear(
 ) -> Result<[u8; 32]> {
     validate(accounts, endpoint_program, CLEAR_MIN_ACCOUNTS_LEN)?;
     require_keys_eq!(accounts[1].key(), receiver, ErrorCode::ConstraintAddress);
+    require_keys_eq!(params.receiver, receiver, ErrorCode::ConstraintAddress);
 
     let cpi_accounts = Clear {
         signer: accounts[1].clone(),
@@ -300,11 +307,146 @@ pub fn clear(
     Ok(result.get())
 }
 
-/// Sends a composed message to another program on the same chain.
+/// Skips the next inbound nonce on the Endpoint messaging channel.
+///
+/// # Accounts layout
+/// The `accounts` slice must follow the `Skip` struct field order:
+///
+/// 0. `endpoint_program`
+/// 1. `signer`
+/// 2. `oapp_registry`
+/// 3. `nonce`
+/// 4. `pending_inbound_nonce`
+/// 5. `payload_hash`
+/// 6. `endpoint`
+/// 7. `event_authority`
+/// 8. `program`
+/// 9. remaining accounts (variable length)
+///
+/// # Accounts validation
+/// - `accounts[0]` must equal the caller-supplied `endpoint_program` parameter.
+/// - `accounts[1]` is the `signer` — pinned to `receiver`, as is `params.receiver`.
+pub fn skip(
+    endpoint_program: Pubkey,
+    receiver: Pubkey,
+    accounts: &[AccountInfo],
+    seeds: &[&[u8]],
+    params: SkipParams,
+) -> Result<()> {
+    validate(accounts, endpoint_program, SKIP_MIN_ACCOUNTS_LEN)?;
+    require_keys_eq!(accounts[1].key(), receiver, ErrorCode::ConstraintAddress);
+    require_keys_eq!(params.receiver, receiver, ErrorCode::ConstraintAddress);
+
+    let cpi_accounts = Skip {
+        signer: accounts[1].clone(),
+        oapp_registry: accounts[2].clone(),
+        nonce: accounts[3].clone(),
+        pending_inbound_nonce: accounts[4].clone(),
+        payload_hash: accounts[5].clone(),
+        endpoint: accounts[6].clone(),
+        event_authority: accounts[7].clone(),
+        program: accounts[8].clone(),
+    };
+    endpoint::cpi::skip(
+        make_cpi_ctx(accounts, cpi_accounts, SKIP_MIN_ACCOUNTS_LEN).with_signer(&[seeds]),
+        params,
+    )
+}
+
+/// Permanently burns a verified payload hash so it can never be executed or re-verified.
+///
+/// # Accounts layout
+/// The `accounts` slice must follow the `Burn` struct field order:
+///
+/// 0. `endpoint_program`
+/// 1. `signer`
+/// 2. `oapp_registry`
+/// 3. `nonce`
+/// 4. `payload_hash`
+/// 5. `endpoint`
+/// 6. `event_authority`
+/// 7. `program`
+/// 8. remaining accounts (variable length)
+///
+/// # Accounts validation
+/// - `accounts[0]` must equal the caller-supplied `endpoint_program` parameter.
+/// - `accounts[1]` is the `signer` — pinned to `receiver`, as is `params.receiver`.
+pub fn burn(
+    endpoint_program: Pubkey,
+    receiver: Pubkey,
+    accounts: &[AccountInfo],
+    seeds: &[&[u8]],
+    params: BurnParams,
+) -> Result<()> {
+    validate(accounts, endpoint_program, BURN_MIN_ACCOUNTS_LEN)?;
+    require_keys_eq!(accounts[1].key(), receiver, ErrorCode::ConstraintAddress);
+    require_keys_eq!(params.receiver, receiver, ErrorCode::ConstraintAddress);
+
+    let cpi_accounts = Burn {
+        signer: accounts[1].clone(),
+        oapp_registry: accounts[2].clone(),
+        nonce: accounts[3].clone(),
+        payload_hash: accounts[4].clone(),
+        endpoint: accounts[5].clone(),
+        event_authority: accounts[6].clone(),
+        program: accounts[7].clone(),
+    };
+    endpoint::cpi::burn(
+        make_cpi_ctx(accounts, cpi_accounts, BURN_MIN_ACCOUNTS_LEN).with_signer(&[seeds]),
+        params,
+    )
+}
+
+/// Temporarily nilifies a payload hash (blocks execution until re-verification).
+///
+/// Note: `nilify` has no Endpoint settings account.
+///
+/// # Accounts layout
+/// The `accounts` slice must follow the `Nilify` struct field order:
+///
+/// 0. `endpoint_program`
+/// 1. `signer`
+/// 2. `oapp_registry`
+/// 3. `nonce`
+/// 4. `pending_inbound_nonce`
+/// 5. `payload_hash`
+/// 6. `event_authority`
+/// 7. `program`
+/// 8. remaining accounts (variable length)
+///
+/// # Accounts validation
+/// - `accounts[0]` must equal the caller-supplied `endpoint_program` parameter.
+/// - `accounts[1]` is the `signer` — pinned to `receiver`, as is `params.receiver`.
+pub fn nilify(
+    endpoint_program: Pubkey,
+    receiver: Pubkey,
+    accounts: &[AccountInfo],
+    seeds: &[&[u8]],
+    params: NilifyParams,
+) -> Result<()> {
+    validate(accounts, endpoint_program, NILIFY_MIN_ACCOUNTS_LEN)?;
+    require_keys_eq!(accounts[1].key(), receiver, ErrorCode::ConstraintAddress);
+    require_keys_eq!(params.receiver, receiver, ErrorCode::ConstraintAddress);
+
+    let cpi_accounts = Nilify {
+        signer: accounts[1].clone(),
+        oapp_registry: accounts[2].clone(),
+        nonce: accounts[3].clone(),
+        pending_inbound_nonce: accounts[4].clone(),
+        payload_hash: accounts[5].clone(),
+        event_authority: accounts[6].clone(),
+        program: accounts[7].clone(),
+    };
+    endpoint::cpi::nilify(
+        make_cpi_ctx(accounts, cpi_accounts, NILIFY_MIN_ACCOUNTS_LEN).with_signer(&[seeds]),
+        params,
+    )
+}
+
+/// Queues a composed message for another program on the same chain.
 ///
-/// Composition allows an OApp to trigger follow-up logic in a separate program after
-/// receiving a cross-chain message. The Endpoint stores the composed message hash,
-/// and the target program's `lz_compose` handler is invoked to process it.
+/// The Endpoint stores the composed message hash and emits an event. The target program's
+/// `lz_compose` handler is invoked separately; this CPI does not execute the composer.
 ///
 /// # Accounts layout
 /// The `accounts` slice must follow the `SendCompose` struct field order:

package/src/errors.rs

@@ -1,10 +1,9 @@
 use anchor_lang::error_code;
 
 /// Custom error codes for OApp operations
-#[error_code]
+// The offset keeps these codes distinct from RBAC's and the consuming program's own errors.
+#[error_code(offset = 11000)]
 pub enum OAppError {
-    #[msg("Invalid address lookup table")]
-    InvalidAddressLookupTable,
     #[msg("Invalid options")]
     InvalidOptions,
     #[msg("Invalid options length")]
@@ -13,4 +12,6 @@ pub enum OAppError {
     NoPeer,
     #[msg("TLV update would change entry size")]
     TlvLengthMismatch,
+    #[msg("Planner output must be a writable, empty scratch account owned by the planner")]
+    InvalidPlanOutput,
 }

package/src/lib.rs

@@ -12,13 +12,16 @@
 //! - **Account macros** – re-exported from [`oapp_macros`] to generate boilerplate Anchor account
 //!   structs for standard OApp instructions.
 //! - **Types & traits** – shared parameter / return structs, the [`OAppState`] trait for PDA signer
-//!   seeds, and messaging option builders.
+//!   seeds, [`MessagingChannelRoles`] for messaging-channel RBAC, and messaging option builders.
+//! - **Receive / compose planning** – plan formats ([`lz_receive_types_v3`],
+//!   [`lz_compose_types_v3`]) and the [`lz_plan`] output writer.
 
 pub mod common;
 pub mod endpoint_cpi;
 pub mod events;
-pub mod lz_compose_types_v2;
-pub mod lz_receive_types_v2;
+pub mod lz_compose_types_v3;
+pub mod lz_plan;
+pub mod lz_receive_types_v3;
 pub mod oapp_info;
 pub mod options;
 pub mod types;
@@ -59,15 +62,12 @@ pub const RECEIVE_LIBRARY_CONFIG_SEED: &[u8] = b"ReceiveLibraryConfig";
 // Event
 pub const EVENT_SEED: &[u8] = b"__event_authority";
 
-// PDA seed helpers below use `Box::leak` to produce the `&'static [&'static [u8]]`
-// shape required by Anchor's `#[account(seeds = ...)]` attribute. Each call leaks
-// ~64 bytes. **SVM-only**: harmless on-chain because the BPF VM allocator is torn
-// down at the end of every transaction, so leaks never accumulate. Do not call
-// these from long-running off-chain Rust (native test runners, indexers, CLIs) —
-// derive PDAs with stack-local arrays in those contexts instead.
-
-/// PDA seeds for an OApp's `lz_receive_types_accounts` PDA.
-/// Seed shape: [LZ_RECEIVE_TYPES_SEED, oapp_key]
+/// PDA seeds for an OApp's `lz_receive_types_accounts` PDA: `[LZ_RECEIVE_TYPES_SEED, oapp_key]`.
+///
+/// Uses `Box::leak` to produce the `'static` shape Anchor's `#[account(seeds = ...)]` requires,
+/// leaking ~64 bytes per call. **SVM-only**: on-chain the leak lives only as long as the program's
+/// VM heap. Do not call this from long-running off-chain Rust (native test runners, indexers,
+/// CLIs); derive the PDA with stack-local seeds there.
 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()]))
@@ -80,3 +80,17 @@ pub fn lz_receive_types_seeds(oapp_key: &Pubkey) -> &'static [&'static [u8]] {
 pub trait OAppState<const N: usize> {
     fn signer_seeds(&self) -> [&[u8]; N];
 }
+
+/// Roles gating the `#[oapp]`-generated messaging-channel instructions; the program's role enum
+/// must implement this.
+///
+/// The DefaultAdmin does not need them: it is the OApp's Endpoint delegate and can clear, skip,
+/// burn and nilify on the Endpoint directly. These roles let other keys do the same through the
+/// OApp. The two are meant to be distinct roles, which the framework does not check.
+pub trait MessagingChannelRoles {
+    /// Role for `clear`, `skip`, and `burn`.
+    fn messaging_channel_manager_role() -> Self;
+
+    /// Role for `nilify`.
+    fn message_nilifier_role() -> Self;
+}

package/src/lz_compose_types_v3.rs

@@ -0,0 +1,72 @@
+//! Compose plan format (planner version 3) and the Endpoint `clear_compose` account helper.
+//!
+//! See `docs/lz-compose-types.md` for how compose planning differs from receive planning.
+use crate::{common::AccountMetaRef, COMPOSED_MESSAGE_HASH_SEED, EVENT_SEED};
+use anchor_lang::prelude::*;
+use solana_keccak_hasher::hash;
+
+/// Planner version returned by `lz_compose_types_info`.
+pub const LZ_COMPOSE_TYPES_VERSION: u8 = 3;
+
+/// Returned by `lz_compose_types_info`: the planner's read-only, app-specific inputs.
+///
+/// The client prepends the payer and the plan scratch account. Account order is part of the
+/// planner ABI, including Anchor's optional-account sentinels.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug)]
+pub struct LzComposeTypesV3Accounts {
+    pub accounts: Vec<Pubkey>,
+}
+
+/// Compose plan written by `lz_compose_types_v3`.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug, PartialEq, Eq)]
+pub struct LzComposeTypesV3Result {
+    /// Execution-context version; selects the account
+    /// [`AddressLocator::Context`](crate::common::AddressLocator::Context) resolves to.
+    pub context_version: u8,
+    /// Executed in order in one transaction. Must contain exactly one `LzCompose`; `Standard`
+    /// instructions may precede or follow it.
+    pub instructions: Vec<ComposeInstruction>,
+}
+
+/// One instruction of a compose plan.
+#[derive(AnchorSerialize, AnchorDeserialize, Clone, Debug, PartialEq, Eq)]
+pub enum ComposeInstruction {
+    /// The delivery: this program's `lz_compose`, called with the original params.
+    LzCompose { accounts: Vec<AccountMetaRef> },
+    /// Any other instruction, submitted as given.
+    Standard { program_id: Pubkey, accounts: Vec<AccountMetaRef>, data: Vec<u8> },
+}
+
+/// Accounts for the Endpoint `clear_compose` CPI, in the order
+/// [`crate::endpoint_cpi::clear_compose`] expects.
+pub fn get_accounts_for_clear_compose(
+    endpoint_program: Pubkey,
+    from: &Pubkey,
+    to: &Pubkey,
+    guid: &[u8; 32],
+    index: u16,
+    composed_message: &[u8],
+) -> Vec<AccountMetaRef> {
+    let (composed_message_account, _) = Pubkey::find_program_address(
+        &[
+            COMPOSED_MESSAGE_HASH_SEED,
+            &from.to_bytes(),
+            &to.to_bytes(),
+            &guid[..],
+            &index.to_be_bytes(),
+            &hash(composed_message).to_bytes(),
+        ],
+        &endpoint_program,
+    );
+
+    let (event_authority_account, _) =
+        Pubkey::find_program_address(&[EVENT_SEED], &endpoint_program);
+
+    vec![
+        AccountMetaRef { pubkey: endpoint_program.into(), is_writable: false },
+        AccountMetaRef { pubkey: (*to).into(), is_writable: false },
+        AccountMetaRef { pubkey: composed_message_account.into(), is_writable: true },
+        AccountMetaRef { pubkey: event_authority_account.into(), is_writable: false },
+        AccountMetaRef { pubkey: endpoint_program.into(), is_writable: false },
+    ]
+}

package/src/lz_plan.rs

@@ -0,0 +1,71 @@
+//! Output transport for `lz_receive_types_v3` / `lz_compose_types_v3` plans.
+//!
+//! The caller supplies the output ("scratch") account: it creates it with its own keypair in a
+//! top-level `SystemProgram::create_account`, owned by the planner program, ahead of the planner
+//! instruction. The program never allocates or resizes the scratch and pays no rent. A top-level
+//! create is not a CPI, so `MAX_PERMITTED_DATA_INCREASE` does not apply and the caller alone
+//! decides how large the scratch is.
+//!
+//! The plan is written Borsh-encoded at offset 0, with no header. [`write()`] returns the encoded
+//! length whether or not the plan fit, and planners return that as their instruction's return data:
+//! a caller whose scratch was too small re-simulates with a larger one, and otherwise reads
+//! `data[..length]` from the same simulation's post-state. The scratch's own length says nothing
+//! about the plan.
+//!
+//! Planning is meant to be simulated, not submitted, but nothing here enforces that: a signed
+//! transaction can run a planner and leave the scratch account allocated.
+
+use crate::errors::OAppError;
+use anchor_lang::prelude::*;
+
+fn validate_output(program: &Pubkey, output: &AccountInfo) -> Result<()> {
+    // Checked here so a planner that forgets `mut` fails with this error, not the runtime's.
+    require!(output.is_writable, OAppError::InvalidPlanOutput);
+    require_keys_eq!(*output.owner, *program, OAppError::InvalidPlanOutput);
+    require!(output.try_borrow_data()?.iter().all(|byte| *byte == 0), OAppError::InvalidPlanOutput);
+    Ok(())
+}
+
+/// Writes `plan` into `output` if it fits, and returns the plan's encoded length either way.
+///
+/// Fails with `InvalidPlanOutput` unless `output` is writable, owned by `program`, and all of its
+/// data is zero. Taking a [`Signer`] means a caller can only hand over an account whose key it
+/// holds, and the all-zero check keeps the planner from overwriting initialized program state or an
+/// earlier plan.
+pub fn write<T: AnchorSerialize>(program: &Pubkey, output: &Signer, plan: &T) -> Result<u32> {
+    let output = output.as_ref();
+    validate_output(program, output)?;
+    let payload = borsh::to_vec(plan)?;
+    if payload.len() <= output.data_len() {
+        output.try_borrow_mut_data()?[..payload.len()].copy_from_slice(&payload);
+    }
+    // A plan is bounded by the SBF heap, far below u32::MAX.
+    Ok(payload.len() as u32)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn output_must_be_writable_owned_and_zeroed() {
+        let (program, key) = (Pubkey::new_unique(), Pubkey::new_unique());
+        let run = |writable: bool, owner: Pubkey, data: Vec<u8>| {
+            let (mut lamports, mut data) = (1, data);
+            let info =
+                AccountInfo::new(&key, true, writable, &mut lamports, &mut data, &owner, false);
+            write(&program, &Signer::try_from(&info).unwrap(), &7u32)
+        };
+        assert_eq!(run(true, program, vec![0; 8]).unwrap(), 4);
+        for (writable, owner, data) in [
+            (false, program, vec![0; 8]),
+            (true, Pubkey::new_unique(), vec![0; 8]),
+            (true, program, vec![1; 8]),
+        ] {
+            assert_eq!(
+                run(writable, owner, data).unwrap_err(),
+                OAppError::InvalidPlanOutput.into()
+            );
+        }
+    }
+}