@layerzerolabs/framework-solana-anchor-trait 0.2.100 → 0.2.102

package/README.md

@@ -66,6 +66,36 @@ For required instructions, no default exists. The implementor must provide a han
 
 Unannotated functions whose identifiers collide with managed instruction names are rejected at compile time. Such functions must be annotated with the override attribute (e.g. `#[oapp_instruction]`) to disambiguate intent.
 
+## When to Define a Trait
+
+A trait built on `anchor-trait` exists to serve one or both of two motivations. Use this section to decide whether your work warrants a new trait, or whether a lighter mechanism (program-local handlers, plain macros, a direct dependency) would suffice.
+
+### Motivation 1: Shared Default Behavior with Override
+
+> Analogous to Solidity's `abstract contract` — a partial implementation that downstream contracts inherit and selectively override.
+
+Multiple programs are expected to implement the same set of instructions, and the trait author wants to ship a default implementation that each program can adopt as-is or override per-instruction. Without a trait, every program copies the same handlers; as the standard evolves, the copies drift silently because no central authority enforces signature consistency.
+
+A trait satisfies this motivation by exposing default implementations (provided instructions) that implementors consume through the override resolution algorithm. The framework enforces at compile time that every implementor either accepts the default or supplies a handler whose signature matches the trait declaration — drift can no longer happen silently.
+
+### Motivation 2: Compile-Time-Enforced Surface for External Callers
+
+> Analogous to Solidity's `interface` — a signature-only contract that every implementation must conform to.
+
+External callers — off-chain clients such as generic SDKs, wallets, indexers, and explorers, or other on-chain programs invoking via CPI — require a stable and predictable surface across all implementations of the standard. Every implementor must honour the same instruction signatures, account layouts, and PDA seed conventions so that one generic caller can target any deployment.
+
+A trait satisfies this motivation by publishing a canonical instruction surface — parameter types, return types, account layouts, view-ness, and seed constants — that the framework enforces at compile time. A non-conforming implementor produces a build-time error rather than a runtime CPI failure or a silently-broken SDK call.
+
+### Three Combination Scenarios
+
+| Reusability | Composability | Recommendation                                                                                                                                                                                      |
+| ----------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Yes         | Yes           | Define a trait. Default implementations and the published interface come from a single source of truth. Most traits in this codebase fall here.                                                     |
+| Yes         | No            | Define a trait. Provided instructions and override resolution still apply; the published interface is consumed by implementors themselves rather than by external callers.                          |
+| No          | Yes           | Define a trait with all instructions marked required (`default_impl: None`). The value lies in compile-time enforcement of signatures and account layouts; no default behaviour needs to be shared. |
+
+If neither motivation applies, do not define a trait. There is no reuse to factor out and no interface to standardise; use program-local code or macros directly.
+
 ## Defining a Trait
 
 The following steps describe how to create a new instruction trait using the framework.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@layerzerolabs/framework-solana-anchor-trait",
-  "version": "0.2.100",
+  "version": "0.2.102",
   "private": false,
   "license": "MIT",
   "type": "module",
@@ -14,10 +14,10 @@
     "rustfmt.toml"
   ],
   "devDependencies": {
-    "@layerzerolabs/build-utils-solana": "0.2.100",
-    "@layerzerolabs/typescript-configuration": "0.2.100",
-    "@layerzerolabs/tsup-configuration": "0.2.100",
-    "@layerzerolabs/vm-tooling-solana": "0.2.100"
+    "@layerzerolabs/build-utils-solana": "0.2.102",
+    "@layerzerolabs/typescript-configuration": "0.2.102",
+    "@layerzerolabs/tsup-configuration": "0.2.102",
+    "@layerzerolabs/vm-tooling-solana": "0.2.102"
   },
   "publishConfig": {
     "access": "restricted",