Runtime idl transaction wrapper api

[3esmit]

🎯 Purpose

Implement #245 with an ergonomic runtime-IDL transaction-building API in
spel::tx. Applications bind a public or private program once, provide named
IDL inputs, and receive native Wallet transaction types.

The new builder API prepares transactions only. It does not submit, poll,
confirm, print, or change CLI behavior; the application submits through
WalletCore.

⚙️ Approach

• Add SpelProgram, reusable program bindings, public/private instruction
  builders, SpelInput, and structured build errors under spel::tx.
• Reuse the existing resolver for IDL validation, account/PDA resolution,
  argument parsing, identity checks, duplicate detection, and serialization.
• Accept named scalar, JSON, account, and rest-account inputs; preserve
  established CLI-compatible argument formats while adding canonical JSON.
• Delegate directly to WalletCore::build_pub_tx and
  WalletCore::build_privacy_preserving_tx, returning their native results
  without a transaction, Wallet, send, or confirmation wrapper.
• Add preflight errors only for bare IDs inferred as public signer or
  initialized accounts; explicit AccountIdentity values remain a Wallet
  contract.
• Document the high-level API beside the direct resolver escape hatch and
  add hermetic plus sequencer-backed build-only coverage.
• Run the build-only check before existing privacy smoke CLI submissions;
  use the existing --lez-rev option for commit-pinned LEZ smoke inputs.

🧪 How to Test

Run from the repository root:

cargo fmt --all -- --check
cargo test -p spel
cargo clippy -p spel --all-targets
cargo build -p spel
cargo run -p spel -- init --help
bash -n scripts/smoke-test-privacy.sh

Run scripts/smoke-test-privacy.sh in its existing LEZ smoke environment. It
executes the ignored runtime-IDL integration test, verifies build-only public
and private transactions do not reach the sequencer or change relevant state,
then runs the existing public and privacy-preserving CLI submission checks.

🔗 Dependencies

• SPEL PR #248 provides the resolver API this branch extends.
• LEZ PR #614 provides the WalletCore build-only methods pinned by this branch until a compatible release tag is available.

🔜 Future Work

• Adopt the resolver inside CLI internals in a separate behavior-preserving change.
• Consider CLI behavior or dry-run changes only after internal adoption is complete.
• Add generic private-PDA reuse or update only when WalletCore exposes the required binding contract with end-to-end coverage.
• Propose additional input conversions or public dry-run metadata separately.

📋 PR Completion Checklist

• Complete PR description
• Implement the core functionality
• Add/update tests
• Add/update documentation and inline comments

[Copilot]

Pull request overview

Implements issue #245 by adding a runtime-IDL transaction preparation API under spel::tx, allowing applications to bind a program once, provide named IDL inputs, and build native Wallet transaction types (public or privacy-preserving) without submitting/polling/printing.

Changes:

• Added spel::tx resolver + ergonomic builder API (SpelProgram, bound programs, fluent .input(...), resolve() and build(&WalletCore)), plus structured errors.
• Added canonical JSON support for container arguments while preserving legacy CLI-compatible argument forms, PDA seed handling, and deterministic PDA resolution.
• Updated LEZ dependency pinning / crate renames (nssa* → lee* via package), environment variable naming, smoke scripts, and added build-only smoke coverage.

Reviewed changes

Copilot reviewed 32 out of 34 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/e2e/fixture_program/Cargo.toml	Pins LEZ dependency to a specific commit and aliases lee_core as nssa_core for fixtures.
test-modules/test_modules_ffi/Cargo.toml	Updates LEZ deps to commit rev and switches spel-framework-core to workspace path.
spel-framework/Cargo.toml	Updates LEZ deps to commit rev and aliases lee/lee_core back to nssa/nssa_core.
spel-framework-macros/src/lib.rs	Updates macro-generated host input read function to read_lee_inputs.
spel-framework-core/src/pda.rs	Adds private-PDA derivation helper with explicit identifier; refactors seed combining.
spel-framework-core/src/lib.rs	Updates re-export to read_lee_inputs.
spel-framework-core/Cargo.toml	Pins LEZ deps to commit rev and aliases lee/lee_core.
spel-ffi-compile-test/Cargo.toml	Updates LEZ deps to commit rev and aliases lee/lee_core.
spel-client-gen/src/logos_module_codegen.rs	Updates wallet home env var used by generated Qt client glue.
spel-client-gen/src/ffi_codegen.rs	Updates generated FFI to use new wallet env var and updated Wallet APIs/transaction enum.
spel-client-gen/src/codegen.rs	Updates generated Rust client code to new Wallet APIs/transaction enum.
spel-cli/tests/runtime_idl_wallet_smoke.rs	Adds ignored integration test ensuring build-only runtime-IDL txs don’t submit or mutate state.
spel-cli/src/tx/value.rs	Adds JSON + legacy parsing/serialization logic for runtime-IDL argument handling.
spel-cli/src/tx/runtime.rs	Adds the fluent runtime-IDL builder API (SpelProgram, builders, build-only wallet delegation).
spel-cli/src/tx/resolution.rs	Adds resolver-only API with structured SpelTxError and IDL validation.
spel-cli/src/tx/pda_resolution.rs	Implements PDA dependency resolution (including private PDAs with identifier validation).
spel-cli/src/tx.rs	Re-exports new spel::tx API and updates transaction submission enum usage.
spel-cli/src/serialize.rs	Aligns CLI serialization with upstream AccountId string serialization behavior.
spel-cli/src/pda.rs	Updates private-PDA derivation to include identifier (defaulting to 0).
spel-cli/src/parse.rs	Improves shared parsing for program_id and normalizes account_id handling.
spel-cli/src/lib.rs	Updates program binary loading for new Program::new signature.
spel-cli/src/inspect.rs	Updates binary inspection path for new Program::new signature.
spel-cli/src/init.rs	Updates init templates for LEZ rename + adds lockfile repinning for zkVM toolchain compatibility.
spel-cli/src/generate_idl.rs	Minor cleanup to avoid unused-result lint in tests.
spel-cli/src/account_inspect.rs	Updates env-var guidance message to LEE_WALLET_HOME_DIR.
spel-cli/Cargo.toml	Pins LEZ deps to commit rev, enables serde_json arbitrary precision, adds build script.
spel-cli/build.rs	Adds macOS linker rpath workaround for pyo3 Python framework linking.
scripts/smoke-test-privacy.sh	Updates smoke flow for LEZ v0.2.0 layout/env changes and adds runtime-IDL build-only step.
scripts/init-e2e-test.sh	Updates sequencer + wallet config discovery to support LEZ v0.2.0 layout.
scripts/ffi-call-test.sh	Updates sequencer + wallet config discovery and guest lockfile repinning.
rust-toolchain.toml	Pins Rust toolchain to match LEZ requirements.
README.md	Documents the new spel::tx runtime-IDL resolution/builder API and resolver escape hatch.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vpavlin]

Status: rebased onto LEZ v0.2.0 main, but upstream-blocked

I merged current main into this branch (LEZ v0.2.0 via #238 + the #232 determinism fix). Results:

• ✅ Builds clean against the pinned LEZ commit; Unit Tests now pass (the rebase resolved the earlier unit-test failure)
• ✅ Clippy, Formatting, E2E Tests, Privacy Smoke Test, Sequencer Setup — all green
• ❌ FFI Call Test and Init E2E still fail — both trace to the LEZ pin, not to this PR's code:

Root cause — this PR depends on an untagged/unmerged LEZ commit. It pins rev = 0400899… = LEZ PR #614 "Add WalletCore build-only transaction APIs", which is v0.2.0 + 1 commit, still open (not merged to LEZ main, no tag).

• FFI Call Test: the scaffold pins the SHA as a tag, so cargo reports failed to find tag 0400899….
• Init E2E: init.rs defaults scaffolds to tag = "v0.2.0" while this PR's framework pins 0400899 → two lee_core versions → expected spel_framework::prelude::AccountWithMetadata, found lee_core::account::AccountWithMetadata.

Unblock path (upstream): LEZ merges #614 → cuts a v0.2.1 tag → this PR re-pins tag = "v0.2.1" (one-liner). Then the scaffold pins are consistent and both checks should pass.

Parking this PR pending LEZ v0.2.1. It's not a code problem on our side — the rebase + conflict resolution are done and it's otherwise green. cc @3esmit

[3esmit]

@vpavlin This is expected, this depends on a PR I made at LEZ (that came from the dependency of spel PR #248 which this PR depends on). While that is not merged and released, this PR keeps blocked. I will keep it clean (rebasing it to main and fixing conflicts). Hope that lands soon.