Merge pull request #46 from lazor-kit/feat/deferred-execution

feat: deferred execution, odometer replay protection, Solita SDK, tx optimization

Author: onspeedhp

CHANGELOG.md

@@ -8,11 +8,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ### Added
 
+- Deferred Execution: 2-transaction flow for large payloads exceeding the ~574-byte limit of a single Secp256r1 Execute tx
+- Authorize instruction (disc=6): TX1 signs over instruction/account hashes, creates DeferredExec PDA
+- ExecuteDeferred instruction (disc=7): TX2 verifies hashes and executes via CPI with vault signing
+- ReclaimDeferred instruction (disc=8): closes expired DeferredExec accounts, refunds rent to original payer
+- DeferredExecAccount (176 bytes): stores instruction/account hashes, wallet, authority, payer, expiry
+- Deferred execution benchmarks (CU + tx size measurements for TX1/TX2)
+- Error codes 3014-3018 for deferred execution (expired, hash mismatch, invalid expiry, unauthorized reclaim)
+- SDK builders: `createAuthorizeIx`, `createExecuteDeferredIx`, `createReclaimDeferredIx`
+- SDK helpers: `findDeferredExecPda`, `computeInstructionsHash`
+- LazorKitClient methods: `authorizeSecp256r1`, `executeDeferredSecp256r1`, `reclaimDeferred`
+- 7 new integration tests for deferred execution (tests-sdk, total now 35)
 - Odometer counter replay protection for Secp256r1 (monotonic u32 per authority)
 - program_id included in challenge hash (cross-program replay prevention)
 - rpId stored on authority account at creation (saves ~14 bytes per transaction)
 - TypeScript SDK (`sdk/solita-client`) with Solita code generation
-- Integration test suite (`tests-sdk/`) with 28 tests across 7 files
+- Integration test suite (`tests-sdk/`) with 35 tests across 8 files
 - Benchmark script for CU and transaction size measurements
 - CompactInstructions accounts hash for anti-reordering protection
 - Session expiry validation (future check + 30-day max duration)

DEVELOPMENT.md

@@ -38,7 +38,7 @@ cargo test
 ### C. IDL Generation (using Shank)
 
 ```bash
-cd program && shank idl -o . --out-filename idl.json -p 2m47smrvCRpuqAyX2dLqPxpAC1658n1BAQga1wRCsQiT
+cd program && shank idl -o . --out-filename idl.json -p FLb7fyAtkfA4TSa2uYcAT8QKHd2pkoMHgmqfnXFXo7ao
 ```
 
 ### D. SDK Generation (using Solita)
@@ -55,7 +55,7 @@ The generate.mjs script reads the Shank IDL, enriches it with accounts/errors/ty
 # Terminal 1: Start local validator with program loaded
 cd tests-sdk && npm run validator:start
 
-# Terminal 2: Run all 28 tests
+# Terminal 2: Run all 35 tests
 cd tests-sdk && npm test
 ```
 
@@ -65,7 +65,7 @@ cd tests-sdk && npm test
 cd tests-sdk && npm run benchmark
 ```
 
-Measures CU usage and transaction sizes for all instructions.
+Measures CU usage and transaction sizes for all instructions, including deferred execution (Authorize TX1 + ExecuteDeferred TX2).
 
 ### G. Program ID Sync
 

README.md

@@ -2,7 +2,7 @@
 
 A high-performance smart wallet program on Solana with passkey (WebAuthn/Secp256r1) authentication, role-based access control, session keys, and replay-safe odometer counters. Built with [pinocchio](https://github.com/febo/pinocchio) for zero-copy serialization.
 
-**Program ID**: `2m47smrvCRpuqAyX2dLqPxpAC1658n1BAQga1wRCsQiT`
+**Program ID**: `FLb7fyAtkfA4TSa2uYcAT8QKHd2pkoMHgmqfnXFXo7ao`
 
 ---
 
@@ -15,6 +15,7 @@ A high-performance smart wallet program on Solana with passkey (WebAuthn/Secp256
 - **Clock-Based Slot Freshness**: 150-slot window via `Clock::get()` — no SlotHashes sysvar needed
 - **Zero-Copy Serialization**: Raw byte casting via pinocchio, no Borsh overhead
 - **CompactInstructions**: Index-based instruction packing for multi-call payloads within Solana's 1,232-byte tx limit
+- **Deferred Execution**: 2-transaction flow for payloads exceeding the tx limit (e.g., Jupiter swaps) -- TX1 authorizes via signature, TX2 executes with full inner instruction space (~1,100 bytes)
 - **CPI Reentrancy Protection**: stack_height check prevents cross-program authentication attacks
 
 ---
@@ -23,13 +24,24 @@ A high-performance smart wallet program on Solana with passkey (WebAuthn/Secp256
 
 | Metric | Normal Transfer | LazorKit (Secp256r1) | LazorKit (Session) |
 |---|---|---|---|
-| Compute Units | 150 | 10,941 | 4,483 |
+| Compute Units | 150 | 12,441 | 8,983 |
 | Transaction Size | 215 bytes | 658 bytes | 452 bytes |
 | Accounts | 2 | 7 | 7 |
 | Instructions | 1 | 2 | 1 |
 | Transaction Fee | 0.000005 SOL | 0.000005 SOL | 0.000005 SOL |
 
-Session keys are ideal for frequent transactions — they skip the Secp256r1 precompile and use a simple Ed25519 signer, resulting in lower CU and smaller transactions.
+Session keys are ideal for frequent transactions -- they skip the Secp256r1 precompile and use a simple Ed25519 signer, resulting in lower CU and smaller transactions.
+
+### Deferred Execution (Large Payloads)
+
+For operations exceeding the ~574 bytes available in a single Secp256r1 Execute tx (e.g., Jupiter swaps):
+
+| Metric | Immediate Execute | Deferred (2 txs) |
+|---|---|---|
+| Total CU | 12,441 | 18,613 (11,709 + 6,904) |
+| Inner Ix Capacity | ~574 bytes | ~1,100 bytes (1.9x) |
+| Tx Fee | 0.000005 SOL | 0.00001 SOL |
+| Temp Rent | -- | 0.00212 SOL (refunded) |
 
 See [docs/Costs.md](docs/Costs.md) for full cost analysis, session key costs, and CU benchmarks for all instructions.
 
@@ -45,6 +57,7 @@ See [docs/Costs.md](docs/Costs.md) for full cost analysis, session key costs, an
 | Authority (Ed25519) | 80 bytes | 0.001448 |
 | Authority (Secp256r1) | ~125 bytes | 0.001761 |
 | Session | 80 bytes | 0.001448 |
+| DeferredExec | 176 bytes | 0.002116 (temporary, refunded) |
 
 ### Total Wallet Creation
 
@@ -72,6 +85,7 @@ Session rent is refundable after expiry. Ongoing Execute transactions cost only
 | Vault PDA | `["vault", wallet]` | Holds SOL/tokens, program signs via PDA |
 | Authority PDA | `["authority", wallet, id_hash]` | Per-key auth with role + counter |
 | Session PDA | `["session", wallet, session_key]` | Ephemeral sub-key with expiry |
+| DeferredExec PDA | `["deferred", wallet, authority, counter]` | Temporary pre-authorized execution (176 bytes) |
 
 See [docs/Architecture.md](docs/Architecture.md) for struct definitions, security mechanisms, and instruction reference.
 
@@ -82,12 +96,12 @@ See [docs/Architecture.md](docs/Architecture.md) for struct definitions, securit
 ```
 program/src/           Rust smart contract (pinocchio, zero-copy)
   auth/                Ed25519 + Secp256r1/WebAuthn authentication
-  processor/           6 instruction handlers
+  processor/           9 instruction handlers
   state/               Account data structures (NoPadding)
 sdk/solita-client/     TypeScript SDK (Solita-generated + hand-written utils)
   src/generated/       Auto-generated instructions, accounts, errors
   src/utils/           Instruction builders, PDA helpers, signing utils
-tests-sdk/             Integration tests (vitest, 28 tests)
+tests-sdk/             Integration tests (vitest, 35 tests)
 docs/                  Architecture, cost analysis
 audits/                Audit reports
 ```
@@ -138,14 +152,14 @@ See [sdk/solita-client/README.md](sdk/solita-client/README.md) for full API refe
 # Start local validator with program loaded
 cd tests-sdk && npm run validator:start
 
-# Run all 28 integration tests
+# Run all 35 integration tests
 npm test
 
 # Run CU benchmarks
 npm run benchmark
 ```
 
-Tests cover: wallet lifecycle, authority management, execute, sessions, replay protection, counter edge cases, and end-to-end workflows.
+Tests cover: wallet lifecycle, authority management, execute, deferred execution, sessions, replay protection, counter edge cases, and end-to-end workflows.
 
 See [DEVELOPMENT.md](DEVELOPMENT.md) for full development workflow.
 

assertions/src/lib.rs

@@ -11,7 +11,7 @@ use pinocchio_pubkey::declare_id;
 use pinocchio_system::ID as SYSTEM_ID;
 
 // LazorKit Program ID
-declare_id!("2m47smrvCRpuqAyX2dLqPxpAC1658n1BAQga1wRCsQiT");
+declare_id!("FLb7fyAtkfA4TSa2uYcAT8QKHd2pkoMHgmqfnXFXo7ao");
 
 #[allow(unused_imports)]
 use std::mem::MaybeUninit;

docs/Architecture.md

@@ -48,6 +48,7 @@ pub enum AccountDiscriminator {
     Wallet = 1,
     Authority = 2,
     Session = 3,
+    DeferredExec = 4,
 }
 ```
 
@@ -109,13 +110,36 @@ pub struct SessionAccount {
 // Total: 1+1+1+5+32+32+8 = 80 bytes
 ```
 
-### D. Vault PDA
+### D. DeferredExecAccount (176 bytes)
+
+Seeds: `["deferred", wallet_pubkey, authority_pubkey, counter_le(4)]`
+
+```rust
+#[repr(C, align(8))]
+pub struct DeferredExecAccount {
+    pub discriminator: u8,           // 4 = DeferredExec
+    pub version: u8,
+    pub bump: u8,
+    pub _padding: [u8; 5],
+    pub instructions_hash: [u8; 32], // SHA256 of serialized compact instructions
+    pub accounts_hash: [u8; 32],     // SHA256 of all account pubkeys referenced
+    pub wallet: Pubkey,              // 32 bytes
+    pub authority: Pubkey,           // 32 bytes — the authority that authorized
+    pub payer: Pubkey,               // 32 bytes — receives rent refund on close
+    pub expires_at: u64,             // Absolute slot at which this expires
+}
+// Total: 1+1+1+5+32+32+32+32+32+8 = 176 bytes
+```
+
+Temporary account created during `Authorize` (tx1) and closed during `ExecuteDeferred` (tx2). Uses the authority's odometer counter as a seed nonce, ensuring unique PDAs per authorization. Expired accounts can be reclaimed via `ReclaimDeferred`.
+
+### E. Vault PDA
 
 Seeds: `["vault", wallet_pubkey]`
 
 No data allocated. Holds SOL. Program signs for it via PDA seeds during Execute.
 
-## 5. Instructions (6 total)
+## 5. Instructions (9 total)
 
 ### CreateWallet (discriminator: 0)
 
@@ -155,6 +179,35 @@ No data allocated. Holds SOL. Program signs for it via PDA seeds during Execute.
 - Validates expires_at: must be in future, max ~30 days.
 - Accounts: payer, wallet, authorizer, session, system_program, rent_sysvar.
 
+### Authorize (discriminator: 6) — Deferred Execution TX1
+
+- Creates a DeferredExec PDA storing pre-authorized instruction/account hashes.
+- Only Secp256r1 Owner/Admin can authorize (not Ed25519, not Spender).
+- Signed payload: `instructions_hash || accounts_hash` (64 bytes).
+- Expiry offset bounded to 10-9,000 slots (~4 seconds to ~1 hour).
+- Uses the authority's odometer counter (post-increment) as PDA seed nonce.
+- Instruction data: `[instructions_hash(32)][accounts_hash(32)][expiry_offset(2)][auth_payload(variable)]`.
+- Accounts: payer, wallet, authority, deferred_exec, system_program, rent_sysvar, sysvar_instructions.
+
+### ExecuteDeferred (discriminator: 7) — Deferred Execution TX2
+
+- Verifies compact instructions against stored hashes, executes via CPI with vault PDA signing.
+- Closes the DeferredExec account before CPI (close-before-execute pattern).
+- Verifies both instructions_hash and accounts_hash match stored values.
+- Checks expiry (must not be past `expires_at` slot).
+- Refunds rent to the original payer (stored in DeferredExec).
+- Self-reentrancy protection: rejects CPI back into this program.
+- Instruction data: `[compact_instructions(variable)]`.
+- Accounts: payer, wallet, vault, deferred_exec, refund_destination, [remaining accounts...].
+
+### ReclaimDeferred (discriminator: 8)
+
+- Closes an expired DeferredExec account and refunds rent to the original payer.
+- Only the original payer (stored in `deferred.payer`) can reclaim.
+- Can only be called after `expires_at` has passed.
+- No instruction data (discriminator only).
+- Accounts: payer, deferred_exec, refund_destination.
+
 ## 6. CompactInstructions Format
 
 Binary format for packing multiple instructions into Execute:
@@ -175,7 +228,32 @@ Overhead per instruction: 4 bytes + num_accounts. Replaces 32-byte pubkeys with
 
 For Secp256r1 Execute, the signed payload includes a SHA256 hash of all account pubkeys referenced by the compact instructions. This prevents account reordering attacks where an attacker could swap recipient addresses while keeping the signature valid.
 
-## 7. Auth Payload Layout (Secp256r1)
+## 7. Deferred Execution
+
+2-transaction flow for payloads exceeding the ~574 bytes available in a single Secp256r1 Execute transaction (e.g., Jupiter swaps with complex routing).
+
+### Flow
+
+1. **TX1 (Authorize)**: Client computes `instructions_hash = SHA256(packed_compact_instructions)` and `accounts_hash = SHA256(all_referenced_pubkeys)`. These hashes are signed via Secp256r1 and stored in a DeferredExec PDA. The authority's odometer counter is incremented.
+2. **TX2 (ExecuteDeferred)**: Any signer submits the full compact instructions. The program verifies both hashes match, checks expiry, closes the DeferredExec account, and executes via CPI with vault signing.
+
+### Capacity
+
+| Path | Inner Ix Capacity | Total CU | Tx Fee |
+|---|---|---|---|
+| Immediate Execute | ~574 bytes | 12,441 | 0.000005 SOL |
+| Deferred (2 txs) | ~1,100 bytes (1.9x) | 18,613 | 0.00001 SOL |
+
+### Security Properties
+
+- **Hash binding**: Both instruction content and account ordering are hash-verified.
+- **Replay protection**: Odometer counter used as PDA seed nonce — each authorization gets a unique PDA.
+- **Expiry**: 10-9,000 slot window (~4s to ~1h). Prevents stale authorizations.
+- **Role gating**: Only Secp256r1 Owner/Admin can authorize.
+- **Close-before-CPI**: DeferredExec account is closed before CPI execution, avoiding stale-pointer issues with `invoke_signed_unchecked`. Transaction reverts atomically if any CPI fails.
+- **Rent recovery**: `ReclaimDeferred` allows original payer to reclaim rent from expired, unexecuted authorizations.
+
+## 8. Auth Payload Layout (Secp256r1)
 
 ```
 [slot: u64 LE]              // 8 bytes  -- Clock-based slot freshness
@@ -190,7 +268,7 @@ Compared to the previous layout, 3 optimizations reduce the per-transaction payl
 - **SlotHashes index**: removed (slot freshness via `Clock::get()` instead of sysvar lookup)
 - **rpId**: stored on the authority account at creation, not sent per-tx (saves ~12 bytes)
 
-## 8. Project Structure
+## 9. Project Structure
 
 ```
 program/
@@ -205,16 +283,20 @@ program/
     processor/
       create_wallet.rs
       manage_authority.rs     AddAuthority + RemoveAuthority
-      execute.rs              CompactInstruction execution
+      execute.rs              CompactInstruction execution (immediate)
+      authorize.rs            Deferred execution TX1 (creates DeferredExec PDA)
+      execute_deferred.rs     Deferred execution TX2 (verifies + executes)
+      reclaim_deferred.rs     Closes expired DeferredExec accounts
       create_session.rs
       transfer_ownership.rs
     state/
       wallet.rs               WalletAccount (8 bytes)
       authority.rs            AuthorityAccountHeader (48 bytes)
       session.rs              SessionAccount (80 bytes)
+      deferred.rs             DeferredExecAccount (176 bytes)
     compact.rs                CompactInstruction serialization
     utils.rs                  PDA initialization, stack_height check
-    error.rs                  AuthError enum (3001-3013)
+    error.rs                  AuthError enum (3001-3018)
     entrypoint.rs             Instruction routing
 sdk/solita-client/
   src/
@@ -226,5 +308,5 @@ sdk/solita-client/
       secp256r1.ts            Challenge hash + auth payload builders
       packing.ts              CompactInstruction packing
       errors.ts               Error code mapping
-tests-sdk/                    Integration tests (vitest, 28+ tests)
+tests-sdk/                    Integration tests (vitest, 35 tests)
 ```