@actioncodes/protocol 1.2.2 → 2.0.1

package/LICENSE

@@ -198,4 +198,4 @@
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
-   limitations under the License.
+   limitations under the License.

package/README.md

@@ -1,55 +1,340 @@
-# 🛡️ Action Codes Protocol
+## Action Codes Protocol
 
-![Coverage](https://img.shields.io/badge/coverage-98%-brightgreen)
+The Action Codes Protocol is a lightweight way to prove intent and authorize actions across blockchains, apps, and wallets.
+Instead of heavy signature popups or complex flows, it uses short-lived one-time codes derived from canonical cryptographic messages.
 
-**Action Codes Protocol** enables short-lived, cryptographically verifiable action codes that authorize blockchain transactions and intents without requiring live wallet sessions.
+### This enables:
+- Secure intent binding – the code is cryptographically tied to a wallet/public key.
+- Fast verification – relayers/servers can validate in microseconds.
+- Cross-chain support – adapters handle chain-specific quirks (currently we are supporting Solana)
+- Simple dev UX – just generate → sign → verify.
 
-This repository contains the canonical specifications, SDK modules, and chain adapter interfaces that implement the Action Codes Protocol.
+### What's new in v2 (compared to [v1](https://github.com/otaprotocol/actioncodes))
+- Now we use Bun as core library. We are down to ~3ms per code signature verification on commodity hardware.
+- Canonical Messages only → No ambiguity. Codes are always derived from a canonical serialization (serializeCanonical).
+- No AIPs (Action Codes Improvement Proposals) → Overkill for lightweight protocol.
+- Chain Adapters simplified → They don't enforce business rules; they just provide utilities:
+  - createProtocolMetaIx (for attaching metadata)
+  - parseMeta / verifyTransactionMatchesCode (for checking integrity)
+  - verifyTransactionSignedByIntentOwner (optional stronger guarantee).
+- Errors are typed → Clear ProtocolError.* categories instead of generic fails.
 
----
+### Core Concepts
 
-## ✨ Key Features
+1. Action Codes
+   - A short-lived, one-time code bound to a wallet/public key.
+   - Generated using HMAC/HKDF and canonical serialization.
 
-- 🔐 **Deterministic Code Generation**  
-  Users can generate time-limited codes directly in their wallet or client, without external servers.
+2. Protocol Meta
+   - The "payload" carried with transactions to tie them to action codes.
+   - Versioned, deterministic, size-limited. 
+   - Perfect for attaching to transactions or off-chain messages for tracing.
 
-- ✅ **Signature-Based Verification**  
-  Codes are signed by the wallet, and transactions must be signed by protocol-authorized relayers.
+3. Canonical Message
+   - A deterministic JSON serialization of (pubkey, code, timestamp, optional secret)
+   - Always signed by the user's wallet.
+   - Prevents replay / tampering.
 
-- 🧩 **Meta-Based Intent Encoding**  
-  Each transaction carries an encoded `meta` string for verifiable context across chains.
+## Strategy Architecture
 
-- 🧱 **Chain-Agnostic Design**  
-  Works on Solana today; built for future EVM, Cosmos, and more.
+The Action Codes Protocol supports two main strategies for generating and validating codes:
 
-- 🌐 **Prefix Namespace System**  
-  Enables ecosystem-wide namespacing (e.g. `JUP`, `ME`) for branded intents and UIs.
+### 1. Wallet Strategy (Direct)
 
----
+The **Wallet Strategy** is the simplest approach where codes are generated directly from a user's wallet.
 
-## 📦 Repository Structure
+#### How it works:
+```typescript
+// 1. Get canonical message for signing
+const canonicalMessage = protocol.getCanonicalMessageParts("user-wallet-address");
 
+// 2. Sign the canonical message with user's wallet
+const signature = await userWallet.signMessage(canonicalMessage);
+
+// 3. Generate code with the signed canonical message (secret is optional)
+const result = await protocol.generateCode("wallet", canonicalMessage, signature);
+// Optional: provide secret for enhanced security
+// const result = await protocol.generateCode("wallet", canonicalMessage, signature, "optional-secret");
+
+// 4. Validate code
+const isValid = await protocol.validateCode("wallet", result.actionCode, {
+  chain: "solana",
+  pubkey: "user-wallet-address",
+  signature: signature
+});
+```
+
+#### Key Features:
+- **Signature-based security** - Codes require a valid signature over the canonical message (prevents public key + timestamp attacks)
+- **Direct wallet binding** - Codes are cryptographically tied to the user's public key
+- **Optional secrets** - Users can provide a secret for enhanced security (uses HMAC), or omit it (uses SHA256)
+- **Immediate validation** - No delegation certificates needed
+- **Perfect for** - Direct user interactions, simple authentication flows
+
+#### Security Model:
+- **Signature verification** - All codes require a valid signature over the canonical message
+- **Public key + timestamp attack prevention** - Signatures prevent attackers from generating codes with just public key + timestamp
+- Codes are bound to the specific public key
+- Optional secret provides additional entropy (HMAC vs SHA256)
+- Time-based expiration prevents replay attacks
+- Canonical message signing ensures integrity
+
+### 2. Delegation Strategy (Advanced)
+
+The **Delegation Strategy** allows users to pre-authorize actions through delegation certificates, enabling more complex workflows like relayer services.
+
+#### How it works:
+
+##### Step 1: Create Delegation Certificate
+```typescript
+// User creates a delegation certificate template
+const template = await protocol.createDelegationCertificateTemplate(
+  userPublicKey,
+  3600000, // 1 hour expiration
+  "solana"
+);
+
+// User signs the certificate
+const message = DelegationStrategy.serializeCertificate(template);
+const signature = await userWallet.signMessage(message);
+
+const certificate: DelegationCertificate = {
+  ...template,
+  signature: signature
+};
+```
+
+##### Step 2: Generate Delegated Codes
+```typescript
+// Generate codes using the delegation certificate
+const result = await protocol.generateCode("delegation", certificate);
+const actionCode = result.actionCode;
+```
+
+##### Step 3: Validate Delegated Codes
+```typescript
+// Validate the delegated code with the certificate
+const isValid = await protocol.validateCode(actionCode, "delegation", certificate);
+```
+
+#### Key Features:
+- **Pre-authorization** - Users can authorize actions for a limited time
+- **Relayer support** - Third parties can validate codes without generating them
+- **Certificate-based** - Codes are bound to specific delegation certificates
+- **Time-limited** - Certificates have expiration times
+- **Perfect for** - Relayer services, automated systems, complex workflows
+
+#### Security Model:
+- **Code-Certificate Binding** - Codes are cryptographically bound to their specific certificate
+- **Signature Verification** - Certificate signatures are verified using chain adapters
+- **Delegation ID** - Each certificate has a unique ID derived from its content + signature
+- **Cross-Certificate Protection** - Codes from one certificate cannot be used with another
+- **Relayer Security** - Relayers can validate codes but cannot generate them without the user's signature
+
+#### Important Security Guarantees:
+
+1. **Stolen Delegation IDs are Useless**
+   - Delegation IDs are public identifiers (like transaction hashes)
+   - They cannot be used to generate or validate codes
+   - They're safe to share publicly
+
+2. **Stolen Signatures Cannot Create Valid Codes**
+   - Even if an attacker steals a signature, they cannot create valid codes
+   - Codes are bound to the ENTIRE certificate (not just the signature)
+   - Different certificate data = different code = validation failure
+
+3. **Relayer Code Generation Prevention**
+   - Relayers cannot generate codes even with public certificate data
+   - Certificate hashes include the signature (private user asset)
+   - Only the original user can generate valid codes
+
+4. **Code-Certificate Binding**
+   - Codes are cryptographically linked to their specific certificate
+   - Cross-certificate attacks are impossible
+   - Each certificate produces unique codes
+
+#### Delegation Certificate Structure:
+```typescript
+interface DelegationCertificate {
+  version: "1.0";
+  delegator: string;        // User's public key
+  issuedAt: number;         // Timestamp when issued
+  expiresAt: number;        // Expiration timestamp
+  nonce: string;           // Unique nonce for this certificate
+  chain: string;           // Target blockchain
+  signature: string;       // User's signature of the certificate
+}
+```
+
+#### Delegated Action Code Structure:
+```typescript
+interface DelegatedActionCode {
+  code: string;            // The actual action code
+  pubkey: string;          // User's public key
+  timestamp: number;       // Generation timestamp
+  expiresAt: number;       // Code expiration
+  delegationId: string;    // Hash of the certificate (used internally as secret)
+  delegatedBy: string;     // Who delegated (same as pubkey)
+  // Note: secret field is inherited from ActionCode but not used in delegation
+}
+```
+
+## Use Cases & Examples
+
+### Wallet Strategy Use Cases
+
+#### 1. Simple Authentication
+```typescript
+// User logs into a dApp
+const canonicalMessage = protocol.getCanonicalMessageParts(userWallet.publicKey);
+const signature = await userWallet.signMessage(canonicalMessage);
+const result = await protocol.generateCode("wallet", canonicalMessage, signature);
+
+// dApp validates the code
+const isValid = await protocol.validateCode('wallet', result.actionCode, {
+  chain: "solana",
+  pubkey: userWallet.publicKey,
+  signature: signature
+});
 ```
-/src         - SDK modules (codegen, meta, validator, blockchain adapters)
-/specs       - Formal specifications (AIPs)
-README.md    - You are here
-LICENSE      - Apache 2.0
+
+#### 2. Transaction Authorization
+```typescript
+// User authorizes a specific transaction
+const canonicalMessage = protocol.getCanonicalMessageParts(userWallet.publicKey);
+const signature = await userWallet.signMessage(canonicalMessage);
+const result = await protocol.generateCode("wallet", canonicalMessage, signature);
+// Optional: add secret for enhanced security
+// const result = await protocol.generateCode("wallet", canonicalMessage, signature, `tx-${transactionHash}`);
+
+// Relayer validates before executing
+const isValid = await protocol.validateCode('wallet', result.actionCode, {
+  chain: "solana",
+  pubkey: userWallet.publicKey,
+  signature: signature
+});
+```
+
+### Delegation Strategy Use Cases
+
+#### 1. Relayer Services
+```typescript
+// User pre-authorizes a relayer for 1 hour
+const certificate = await createDelegationCertificate(userWallet, 3600000);
+
+// Relayer can validate codes but not generate them
+const relayer = new RelayerService();
+relayer.registerCertificate(certificate);
+
+// User generates codes that relayer can validate
+const actionCode = await protocol.generateCode("delegation", certificate);
+const isValid = relayer.validateCode(actionCode, certificate);
+```
+
+#### 2. Automated Trading Bots
+```typescript
+// User authorizes trading bot for specific operations
+const tradingCertificate = await createDelegationCertificate(userWallet, 86400000); // 24 hours
+
+// Bot can execute trades using delegated codes
+const tradeCode = await protocol.generateCode("delegation", tradingCertificate);
+// Bot executes trade with this code
+```
+
+#### 3. Multi-Signature Workflows
+```typescript
+// Multiple users can delegate to a shared certificate
+const sharedCertificate = await createSharedDelegationCertificate([
+  user1Wallet,
+  user2Wallet,
+  user3Wallet
+]);
+
+// Any authorized user can generate codes
+const actionCode = await protocol.generateCode("delegation", sharedCertificate);
 ```
 
----
+## Security Considerations
+
+### What Makes Action Codes Secure?
+
+1. **Cryptographic Binding**
+   - Codes are mathematically tied to specific public keys
+   - Impossible to forge without the private key
+
+2. **Time-Limited Validity**
+   - Codes expire automatically
+   - Prevents replay attacks
 
-## 📄 Specifications
+3. **One-Time Use**
+   - Each code is unique and time-bound
+   - Cannot be reused
 
-[Protocol Specifications](./specs/README.md)
+4. **Delegation Security**
+   - Delegation certificates are cryptographically signed
+   - Codes are bound to specific certificates
+   - Cross-certificate attacks are impossible
 
-- [`AIP-0`](./specs/aip-0.md): Action Codes Protocol Architecture
-- [`AIP-1`](./specs/aip-1.md): Protocol Meta Format
-- [`AIP-2`](./specs/aip-2.md): Authority Signature Validation
-- [`AIP-3`](./specs/aip-3.md): Intent Resolution & Routing
-- [`AIP-4`](./specs/aip-4.md): Prefix System
+### Best Practices
+
+1. **Secret Management**
+   - Use cryptographically secure random secrets
+   - Don't reuse secrets across different contexts
+   - Consider using deterministic secrets based on context
+
+2. **Certificate Expiration**
+   - Set appropriate expiration times for delegation certificates
+   - Shorter expiration = higher security
+   - Longer expiration = better UX
+
+3. **Relayer Security**
+   - Only trust relayers with full certificates
+   - Never share private keys with relayers
+   - Monitor relayer behavior
+
+4. **Code Validation**
+   - Always validate codes server-side
+   - Check expiration times
+   - Verify the binding to the correct public key
+
+## Performance
+
+- **Code Generation**: ~1ms per code
+- **Code Validation**: ~3ms per validation
+- **Memory Usage**: Minimal (no state storage required)
+- **Network**: No network calls required for validation
+
+## Getting Started
+
+```bash
+# Install
+npm install @actioncodes/protocol
+
+# Basic usage
+import { ActionCodesProtocol } from '@actioncodes/protocol';
+
+const protocol = new ActionCodesProtocol();
+
+// 1. Get canonical message for signing
+const canonicalMessage = protocol.getCanonicalMessageParts("your-public-key");
+
+// 2. Sign the canonical message with your wallet
+const signature = await yourWallet.signMessage(canonicalMessage);
+
+// 3. Generate a code with the signed canonical message
+const result = await protocol.generateCode("wallet", canonicalMessage, signature);
+// Optional: add secret for enhanced security
+// const result = await protocol.generateCode("wallet", canonicalMessage, signature, "optional-secret");
+
+// 4. Validate a code
+const isValid = await protocol.validateCode("wallet", result.actionCode, {
+  chain: "solana",
+  pubkey: "your-public-key",
+  signature: signature
+});
+```
 
----
+#### Vision
 
-## 📜 License
+Action Codes Protocol aim to be the OTP protocol for blockchains but allowing more than authentication: a simple, universal interaction layer usable across apps, chains, and eventually banks/CBDCs.
 
-This protocol is open source under the [Apache 2.0 License](./LICENSE).

package/dist/ActionCodesProtocol.d.ts

@@ -0,0 +1,37 @@
+import type { ActionCode, CodeGenerationConfig, DelegationCertificate, DelegatedActionCode } from "./types";
+import type { ChainAdapter, ChainWalletStrategyContext } from "./adapters/BaseChainAdapter";
+import { WalletStrategy } from "./strategy/WalletStrategy";
+import { DelegationStrategy } from "./strategy/DelegationStrategy";
+import { SolanaAdapter } from "./adapters/SolanaAdapter";
+export declare class ActionCodesProtocol {
+    private readonly config;
+    private adapters;
+    private _walletStrategy;
+    private _delegationStrategy;
+    constructor(config: CodeGenerationConfig);
+    getConfig(): CodeGenerationConfig;
+    /** Register a chain adapter */
+    registerAdapter(chain: string, adapter: ChainAdapter): void;
+    /** Get a registered adapter */
+    getAdapter(chain: string): ChainAdapter | undefined;
+    /** Typed access to specific adapters */
+    get adapter(): {
+        solana: SolanaAdapter;
+    };
+    /** Access to strategies */
+    get walletStrategy(): WalletStrategy;
+    /** Get canonical message parts for signing (before code generation) */
+    getCanonicalMessageParts(pubkey: string, providedSecret?: string): Uint8Array;
+    get delegationStrategy(): DelegationStrategy;
+    createDelegationCertificateTemplate(userPublicKey: string, durationMs?: number, chain?: string): Omit<DelegationCertificate, "signature">;
+    generateCode(strategy: "wallet", canonicalMessage: Uint8Array, signature: string, providedSecret?: string): {
+        actionCode: ActionCode;
+        canonicalMessage: Uint8Array;
+    };
+    generateCode(strategy: "delegation", certificate: DelegationCertificate): {
+        actionCode: DelegatedActionCode;
+    };
+    validateCode(strategy: "wallet", actionCode: ActionCode, context?: Omit<ChainWalletStrategyContext<unknown>, "canonicalMessageParts">): void;
+    validateCode(strategy: "delegation", actionCode: DelegatedActionCode, certificate: DelegationCertificate): void;
+}
+//# sourceMappingURL=ActionCodesProtocol.d.ts.map

package/dist/ActionCodesProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActionCodesProtocol.d.ts","sourceRoot":"","sources":["../src/ActionCodesProtocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AACjB,OAAO,KAAK,EACV,YAAY,EACZ,0BAA0B,EAC3B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAsB,MAAM,0BAA0B,CAAC;AAI7E,qBAAa,mBAAmB;IAKlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJnC,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,mBAAmB,CAAqB;gBAEnB,MAAM,EAAE,oBAAoB;IASlD,SAAS,IAAI,oBAAoB;IAIxC,+BAA+B;IAC/B,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,IAAI;IAI3D,+BAA+B;IAC/B,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAInD,wCAAwC;IACxC,IAAI,OAAO;gBAEoC,aAAa;MAE3D;IAED,2BAA2B;IAC3B,IAAI,cAAc,mBAEjB;IAED,uEAAuE;IACvE,wBAAwB,CAAC,MAAM,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,UAAU;IAK7E,IAAI,kBAAkB,uBAErB;IAGD,mCAAmC,CACjC,aAAa,EAAE,MAAM,EACrB,UAAU,GAAE,MAAgB,EAC5B,KAAK,GAAE,MAAiB,GACvB,IAAI,CAAC,qBAAqB,EAAE,WAAW,CAAC;IAS3C,YAAY,CACV,QAAQ,EAAE,QAAQ,EAClB,gBAAgB,EAAE,UAAU,EAC5B,SAAS,EAAE,MAAM,EACjB,cAAc,CAAC,EAAE,MAAM,GACtB;QACD,UAAU,EAAE,UAAU,CAAC;QACvB,gBAAgB,EAAE,UAAU,CAAC;KAC9B;IACD,YAAY,CACV,QAAQ,EAAE,YAAY,EACtB,WAAW,EAAE,qBAAqB,GACjC;QACD,UAAU,EAAE,mBAAmB,CAAC;KACjC;IAyBD,YAAY,CACV,QAAQ,EAAE,QAAQ,EAClB,UAAU,EAAE,UAAU,EACtB,OAAO,CAAC,EAAE,IAAI,CAAC,0BAA0B,CAAC,OAAO,CAAC,EAAE,uBAAuB,CAAC,GAC3E,IAAI;IACP,YAAY,CACV,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,mBAAmB,EAC/B,WAAW,EAAE,qBAAqB,GACjC,IAAI;CA0DR"}

package/dist/adapters/BaseChainAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { CanonicalMessageParts, DelegationCertificate } from "../types";
+export interface BaseWalletStrategyContext {
+    chain: string;
+    canonicalMessageParts: CanonicalMessageParts;
+}
+export interface BaseDelegationContext {
+    chain: string;
+    pubkey: string;
+    signature: string;
+    certificate: DelegationCertificate;
+}
+export type ChainWalletStrategyContext<T> = BaseWalletStrategyContext & T;
+export type ChainDelegationStrategyContext<T> = BaseDelegationContext & T;
+export interface ChainAdapter<TCtx = unknown, DCtx = unknown> {
+    verifyWithWallet(context: ChainWalletStrategyContext<TCtx>): boolean;
+    verifyWithDelegation(context: ChainDelegationStrategyContext<DCtx>): boolean;
+}
+export declare abstract class BaseChainAdapter<TCtx, DCtx> implements ChainAdapter<TCtx, DCtx> {
+    abstract verifyWithWallet(context: ChainWalletStrategyContext<TCtx>): boolean;
+    abstract verifyWithDelegation(context: ChainDelegationStrategyContext<DCtx>): boolean;
+}
+//# sourceMappingURL=BaseChainAdapter.d.ts.map

package/dist/adapters/BaseChainAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseChainAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/BaseChainAdapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAG7E,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IAEd,qBAAqB,EAAE,qBAAqB,CAAC;CAC9C;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,MAAM,0BAA0B,CAAC,CAAC,IAAI,yBAAyB,GAAG,CAAC,CAAC;AAC1E,MAAM,MAAM,8BAA8B,CAAC,CAAC,IAAI,qBAAqB,GAAG,CAAC,CAAC;AAC1E,MAAM,WAAW,YAAY,CAAC,IAAI,GAAG,OAAO,EAAE,IAAI,GAAG,OAAO;IAC1D,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;IACrE,oBAAoB,CAAC,OAAO,EAAE,8BAA8B,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC;CAC9E;AAED,8BAAsB,gBAAgB,CAAC,IAAI,EAAE,IAAI,CAAE,YAAW,YAAY,CAAC,IAAI,EAAE,IAAI,CAAC;IACpF,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,CAAC,IAAI,CAAC,GAAG,OAAO;IAC7E,QAAQ,CAAC,oBAAoB,CAAC,OAAO,EAAE,8BAA8B,CAAC,IAAI,CAAC,GAAG,OAAO;CACtF"}

package/dist/adapters/SolanaAdapter.d.ts

@@ -0,0 +1,44 @@
+import { PublicKey, Transaction, VersionedTransaction, TransactionInstruction } from "@solana/web3.js";
+import { BaseChainAdapter, type ChainWalletStrategyContext, type ChainDelegationStrategyContext } from "./BaseChainAdapter";
+import { type ProtocolMetaFields } from "../utils/protocolMeta";
+import type { ActionCode } from "../types";
+export type SolanaContext = {
+    pubkey: string | PublicKey;
+    signature: string;
+};
+/** Union of supported Solana txn types */
+export type SolanaTransaction = Transaction | VersionedTransaction;
+export declare class SolanaAdapter extends BaseChainAdapter<SolanaContext, SolanaContext> {
+    /** Normalize pubkey input to PublicKey */
+    private normalizePubkey;
+    /** Verify the signature over canonical message (protocol-level) */
+    verifyWithWallet(context: ChainWalletStrategyContext<SolanaContext>): boolean;
+    /** Verify delegation certificate signature */
+    verifyWithDelegation(context: ChainDelegationStrategyContext<SolanaContext>): boolean;
+    /** Create a Solana memo instruction carrying protocol meta (for SDK/clients) */
+    static createProtocolMetaIx(meta: ProtocolMetaFields): TransactionInstruction;
+    /** Extract protocol metadata string (memo) from a transaction, or null */
+    getProtocolMeta(tx: SolanaTransaction): string | null;
+    /** Get parsed ProtocolMeta object, or null if none or invalid */
+    parseMeta(tx: SolanaTransaction): ProtocolMetaFields | null;
+    /** List memo instructions from the transaction (legacy & versioned) */
+    private getMemoInstructions;
+    /**
+     * Validate that a transaction's memo meta aligns with the bound `actionCode`.
+     * Throws ProtocolError if validation fails.
+     */
+    verifyTransactionMatchesCode(actionCode: ActionCode, tx: SolanaTransaction): void;
+    /**
+     * Verify that the transaction is signed by the "intendedFor" pubkey
+     * as declared in the protocol meta of the transaction.
+     * Throws ProtocolError if validation fails.
+     */
+    verifyTransactionSignedByIntentOwner(tx: SolanaTransaction): void;
+    /**
+     * Attach protocol meta into a legacy or versioned transaction.
+     *
+     * ⚠️ Note: this mutates the given transaction.
+     */
+    static attachProtocolMeta<T extends SolanaTransaction>(tx: T, meta: ProtocolMetaFields): T;
+}
+//# sourceMappingURL=SolanaAdapter.d.ts.map

package/dist/adapters/SolanaAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SolanaAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/SolanaAdapter.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,SAAS,EACT,WAAW,EACX,oBAAoB,EACpB,sBAAsB,EAEvB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EAAE,gBAAgB,EAAE,KAAK,0BAA0B,EAAE,KAAK,8BAA8B,EAAE,MAAM,oBAAoB,CAAC;AAC5H,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAK3C,MAAM,MAAM,aAAa,GAAG;IAC1B,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,0CAA0C;AAC1C,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,oBAAoB,CAAC;AAEnE,qBAAa,aAAc,SAAQ,gBAAgB,CAAC,aAAa,EAAE,aAAa,CAAC;IAC/E,0CAA0C;IAC1C,OAAO,CAAC,eAAe;IAOvB,mEAAmE;IACnE,gBAAgB,CAAC,OAAO,EAAE,0BAA0B,CAAC,aAAa,CAAC,GAAG,OAAO;IA0B7E,8CAA8C;IAC9C,oBAAoB,CAAC,OAAO,EAAE,8BAA8B,CAAC,aAAa,CAAC,GAAG,OAAO;IAiDrF,gFAAgF;IAChF,MAAM,CAAC,oBAAoB,CACzB,IAAI,EAAE,kBAAkB,GACvB,sBAAsB;IAKzB,0EAA0E;IAC1E,eAAe,CAAC,EAAE,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI;IAerD,iEAAiE;IACjE,SAAS,CAAC,EAAE,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,IAAI;IAM3D,uEAAuE;IACvE,OAAO,CAAC,mBAAmB;IAmC3B;;;OAGG;IACH,4BAA4B,CAC1B,UAAU,EAAE,UAAU,EACtB,EAAE,EAAE,iBAAiB,GACpB,IAAI;IAiCP;;;;OAIG;IACH,oCAAoC,CAAC,EAAE,EAAE,iBAAiB,GAAG,IAAI;IAoEjE;;;;OAIG;IACH,MAAM,CAAC,kBAAkB,CAAC,CAAC,SAAS,iBAAiB,EACnD,EAAE,EAAE,CAAC,EACL,IAAI,EAAE,kBAAkB,GACvB,CAAC;CA+CL"}

package/dist/constants.d.ts

@@ -1,10 +1,8 @@
-export declare const PROTOCOL_VERSION = "1";
-export declare const PROTOCOL_PREFIX = "actioncodes";
-export declare const CODE_LENGTH = 8;
-export declare const CODE_TTL: number;
-export declare const PROTOCOL_CODE_PREFIX = "DEFAULT";
-export declare const MIN_PREFIX_LENGTH = 3;
-export declare const MAX_PREFIX_LENGTH = 12;
+export declare const PROTOCOL_NORMALIZATION = "NFC";
+export declare const PROTOCOL_META_MAX_BYTES = 256;
+export declare const CODE_MIN_LENGTH = 6;
+export declare const CODE_MAX_LENGTH = 24;
+export declare const CODE_DEFAULT_LENGTH = 8;
+export declare const CODE_CHARSET_DIGITS = "0123456789";
 export declare const SUPPORTED_CHAINS: readonly ["solana"];
-export type SupportedChain = (typeof SUPPORTED_CHAINS)[number];
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,gBAAgB,MAAM,CAAC;AACpC,eAAO,MAAM,eAAe,gBAAgB,CAAC;AAC7C,eAAO,MAAM,WAAW,IAAI,CAAC;AAC7B,eAAO,MAAM,QAAQ,QAAgB,CAAC;AACtC,eAAO,MAAM,oBAAoB,YAAY,CAAC;AAC9C,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,eAAO,MAAM,iBAAiB,KAAK,CAAC;AACpC,eAAO,MAAM,gBAAgB,qBAAsB,CAAC;AACpD,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,sBAAsB,QAAQ,CAAC;AAC5C,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C,eAAO,MAAM,eAAe,IAAI,CAAC;AACjC,eAAO,MAAM,eAAe,KAAK,CAAC;AAClC,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAGrC,eAAO,MAAM,mBAAmB,eAAe,CAAC;AAEhD,eAAO,MAAM,gBAAgB,qBAAsB,CAAC"}

package/dist/errors.d.ts

@@ -0,0 +1,63 @@
+export declare enum ProtocolErrorCode {
+    EXPIRED_CODE = "EXPIRED_CODE",
+    INVALID_CODE_FORMAT = "INVALID_CODE_FORMAT",
+    INVALID_SIGNATURE = "INVALID_SIGNATURE",
+    MISSING_META = "MISSING_META",
+    INVALID_META_FORMAT = "INVALID_META_FORMAT",
+    META_MISMATCH = "META_MISMATCH",
+    META_TOO_LARGE = "META_TOO_LARGE",
+    TRANSACTION_NOT_SIGNED_BY_INTENDED_OWNER = "TRANSACTION_NOT_SIGNED_BY_INTENDED_OWNER",
+    INVALID_TRANSACTION_FORMAT = "INVALID_TRANSACTION_FORMAT",
+    INVALID_PUBKEY_FORMAT = "INVALID_PUBKEY_FORMAT",
+    INVALID_INPUT = "INVALID_INPUT",
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD",
+    CRYPTO_ERROR = "CRYPTO_ERROR",
+    INVALID_DIGEST = "INVALID_DIGEST",
+    INVALID_ADAPTER = "INVALID_ADAPTER"
+}
+export declare class ProtocolError extends Error {
+    readonly code: ProtocolErrorCode;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: ProtocolErrorCode, message: string, details?: Record<string, unknown> | undefined);
+    static expiredCode(code: string, expiresAt: number, currentTime: number): ExpiredCodeError;
+    static invalidCodeFormat(code: string, reason: string): InvalidCodeFormatError;
+    static invalidSignature(reason: string): InvalidSignatureError;
+    static missingMeta(): MissingMetaError;
+    static invalidMetaFormat(reason: string): ProtocolError;
+    static metaMismatch(expected: string, actual: string, field: string): MetaMismatchError;
+    static metaTooLarge(maxBytes: number, actualBytes: number): ProtocolError;
+    static transactionNotSignedByIntendedOwner(intended: string, actualSigners: string[]): TransactionNotSignedByIntendedOwnerError;
+    static invalidTransactionFormat(reason: string): ProtocolError;
+    static invalidPubkeyFormat(pubkey: string, reason: string): InvalidPubkeyFormatError;
+    static invalidInput(field: string, value: unknown, reason: string): ProtocolError;
+    static missingRequiredField(field: string): ProtocolError;
+    static cryptoError(operation: string, reason: string): ProtocolError;
+    static invalidDigest(reason: string): ProtocolError;
+    static invalidAdapter(adapter: string): InvalidAdapterError;
+    static create(code: ProtocolErrorCode, message: string, details?: Record<string, unknown>): ProtocolError;
+}
+export declare class ExpiredCodeError extends ProtocolError {
+    constructor(code: string, expiresAt: number, currentTime: number);
+}
+export declare class MissingMetaError extends ProtocolError {
+    constructor();
+}
+export declare class MetaMismatchError extends ProtocolError {
+    constructor(expected: string, actual: string, field: string);
+}
+export declare class TransactionNotSignedByIntendedOwnerError extends ProtocolError {
+    constructor(intended: string, actualSigners: string[]);
+}
+export declare class InvalidPubkeyFormatError extends ProtocolError {
+    constructor(pubkey: string, reason: string);
+}
+export declare class InvalidSignatureError extends ProtocolError {
+    constructor(reason: string);
+}
+export declare class InvalidCodeFormatError extends ProtocolError {
+    constructor(code: string, reason: string);
+}
+export declare class InvalidAdapterError extends ProtocolError {
+    constructor(adapter: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}