@layerzerolabs/program-id-solana-contracts 1.2.64

package/Anchor.toml

@@ -0,0 +1,5 @@
+# This package ships no Anchor program; the [toolchain] section exists only so lz-tool selects the
+# same image the Solana contract tree builds with, instead of falling back to its default.
+[toolchain]
+anchor_version = "1.1.2"
+solana_version = "3.1.10"

package/Cargo.toml

@@ -0,0 +1,6 @@
+[workspace]
+members = ["lib", "tests/probe"]
+resolver = "2"
+
+[profile.release]
+overflow-checks = true

package/README.md

@@ -0,0 +1,55 @@
+# @layerzerolabs/program-id-solana-contracts
+
+A cargo-tracked replacement for `solana_helper::program_id_from_env!`, for Solana programs whose
+address is supplied at build time.
+
+## Usage
+
+```rust
+use anchor_lang::prelude::*;
+use program_id::declare_program_id;
+
+declare_program_id!("OFT_ID", "9UovNrJD8pQyBLheeHNayuG1wJSEAoxkmM14vw5gcsTT");
+```
+
+Takes the program ID from `$OFT_ID`, falling back to the literal. Expand it in a crate that has
+`anchor_lang::prelude::*` in scope.
+
+## Problem
+
+`program_id_from_env!` is a proc macro that calls `std::env::var` while it expands. Cargo's
+fingerprint cannot observe that read, so a rebuild with a different value recompiles nothing and
+re-emits the program ID from the previous build. Nothing fails loudly — the `.so` carries the wrong
+address.
+
+That artifact cannot be repaired after the fact. A program ID is folded into `.text` as BPF `lddw`
+immediates at ~150 sites, and Anchor const-evaluates the `__event_authority` bump from it, so
+changing it is a compilation process, not a patch.
+
+## How it works
+
+`declare_program_id!` expands the `declare_id!` alongside an `option_env!($var)` marker. rustc
+records that marker as an environment dependency of the calling crate, so cargo rebuilds whenever
+the variable changes.
+
+The crate does not depend on `anchor-lang`, so it cannot force an anchor version on a consumer.
+
+## Adopting it
+
+- **Repair the IDL.** `anchor idl build` recovers the address by text-matching `declare_id!`, so any
+  non-literal form yields a garbage `address` field. Chain `add_address_to_idl.py --idl-dir <dir>`
+  (present in the anchor image) after it, which re-derives the address via `cargo expand`.
+- **Pass the variable to every step.** The compile and the IDL build are separate `lz-tool`
+  invocations; both need the same value or the `.so` and the IDL disagree.
+- **Pass it with `lz-tool --env`, not cargo's `[env]` table.** `[env]` does not override a variable
+  already set in the process environment, and `--config` cannot express `force = true`.
+- **Expect a new `.so`.** The marker adds no bytes to the artifact, but replacing a literal
+  `declare_id!` shifts source lines, which moves `panic::Location` constants.
+
+## Tests
+
+- `pnpm test:rebuild` — builds `tests/probe` twice with different IDs without cleaning, and fails if
+  the second build does not follow. Deleting the `option_env!` marker makes it fail.
+- `pnpm test:idl-shape` — expands the probe and asserts `add_address_to_idl.py`'s matcher recovers
+  the probe's declared ID.
+- `pnpm test:unit` — default fallback and base58 decoding.

package/lib/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "program-id"
+version = "0.1.0"
+description = "Cargo-tracked program IDs for Solana programs whose address is supplied at build time"
+edition = "2021"
+license = "MIT"
+
+[lib]
+crate-type = ["lib"]
+name = "program_id"
+
+[dependencies]
+solana-helper = "0.1.0"
+
+[dev-dependencies]
+bs58 = "0.5.1"

package/lib/src/lib.rs

@@ -0,0 +1,57 @@
+//! Cargo-tracked program IDs for Solana programs whose address is supplied at build time.
+//!
+//! `solana_helper::program_id_from_env!` reads the variable inside a proc macro, which cargo's
+//! fingerprint cannot observe: a rebuild with a changed value re-emits the previous program ID.
+//! `declare_program_id!` pairs that read with an `option_env!` marker, which rustc records as an
+//! environment dependency of the calling crate, so cargo rebuilds when the variable changes.
+//!
+//! ```ignore
+//! use anchor_lang::prelude::*;
+//! use program_id::declare_program_id;
+//!
+//! declare_program_id!("OFT_ID", "9UovNrJD8pQyBLheeHNayuG1wJSEAoxkmM14vw5gcsTT");
+//! ```
+//!
+//! No `anchor-lang` dependency: `declare_id!` and `Pubkey` resolve at the call site.
+
+#[doc(hidden)]
+pub use solana_helper::program_id_from_env as __program_id_from_env;
+
+/// Declares the program ID from `$var`, falling back to `$default`, and registers `$var` with
+/// cargo so that changing it forces a rebuild.
+///
+/// Expand this in a crate that has `anchor_lang::prelude::*` in scope.
+#[macro_export]
+macro_rules! declare_program_id {
+    ($var:literal, $default:literal) => {
+        // Sibling item: this expansion is matched under `cargo expand` to repair the IDL address.
+        const _: Option<&str> = option_env!($var);
+        declare_id!(Pubkey::new_from_array($crate::__program_id_from_env!($var, $default)));
+    };
+}
+
+#[cfg(test)]
+mod tests {
+    use super::__program_id_from_env as program_id_from_env;
+
+    // `const` position: `declare_id!` consumes the bytes in const context.
+
+    #[test]
+    fn falls_back_to_the_default_when_the_variable_is_absent() {
+        const ID: [u8; 32] = program_id_from_env!(
+            "LZ_PROGRAM_ID_ABSENT_IN_TESTS",
+            "11111111111111111111111111111111"
+        );
+        assert_eq!(ID, [0u8; 32]);
+    }
+
+    #[test]
+    fn decodes_the_default_from_base58() {
+        const DEFAULT: &str = "9UovNrJD8pQyBLheeHNayuG1wJSEAoxkmM14vw5gcsTT";
+        const ID: [u8; 32] = program_id_from_env!(
+            "LZ_PROGRAM_ID_ABSENT_IN_TESTS",
+            "9UovNrJD8pQyBLheeHNayuG1wJSEAoxkmM14vw5gcsTT"
+        );
+        assert_eq!(ID.to_vec(), bs58::decode(DEFAULT).into_vec().unwrap());
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@layerzerolabs/program-id-solana-contracts",
+  "version": "1.2.64",
+  "private": false,
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "lib",
+    "Anchor.toml",
+    "Cargo.toml",
+    "rust-toolchain.toml",
+    "rustfmt.toml"
+  ],
+  "devDependencies": {
+    "@layerzerolabs/vm-tooling-solana": "1.2.64"
+  },
+  "publishConfig": {
+    "access": "restricted",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "externalRepoConfig": {
+    "targets": [
+      "audit-external",
+      "onesig-client"
+    ]
+  },
+  "scripts": {
+    "allow-read-write": "[ -z \"$CI\" ] || sudo chmod -R a+rwx ./target",
+    "build": "pnpm exec lz-tool --script 'cargo build --locked -p program-id' anchor && pnpm allow-read-write",
+    "build:native": "pnpm exec lz-tool --docker-platform native --script 'cargo build --locked -p program-id' anchor && pnpm allow-read-write",
+    "check": "pnpm exec lz-tool --script 'cargo check --workspace --locked' anchor",
+    "clean": "rm -rf target",
+    "format": "pnpm exec lz-tool --script 'cargo +nightly-2025-06-01 fmt --all' anchor",
+    "format:check": "pnpm exec lz-tool --script 'cargo +nightly-2025-06-01 fmt --all --check' anchor",
+    "lint": "pnpm format:check && pnpm lint:rs",
+    "lint:rs": "pnpm exec lz-tool --script 'cargo clippy --workspace --all-targets --locked -- -D warnings' anchor",
+    "test": "pnpm test:unit && pnpm test:rebuild && pnpm test:idl-shape",
+    "test:idl-shape": "pnpm exec lz-tool --script './tests/assert-idl-shape.sh' anchor",
+    "test:rebuild": "pnpm exec lz-tool --script './tests/assert-rebuild.sh' anchor",
+    "test:unit": "pnpm exec lz-tool --script 'cargo test --locked -p program-id --lib' anchor"
+  }
+}

package/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.92.0"
+components = ["rustfmt", "clippy"]

package/rustfmt.toml

@@ -0,0 +1,23 @@
+# Basic
+hard_tabs = false
+max_width = 100
+use_small_heuristics = "Max"
+# Imports
+imports_granularity = "Crate"
+reorder_imports = true
+# Consistency
+newline_style = "Unix"
+# Format comments
+comment_width = 100
+wrap_comments = true
+# Misc
+chain_width = 80
+spaces_around_ranges = false
+binop_separator = "Front"
+reorder_impl_items = false
+match_arm_leading_pipes = "Preserve"
+match_arm_blocks = true
+match_block_trailing_comma = true
+trailing_comma = "Vertical"
+trailing_semicolon = true
+use_field_init_shorthand = true