Clarify the intended architecture for configurable Wasm transaction plugins

[raushan728]

Summary

While looking into the WasmPlugin TODO, I started tracing the current transaction plugin architecture to understand what would be required for an implementation.

The overall direction is clear:

• allow operator-provided transaction plugins
• keep built-in plugins alongside external plugins
• load plugins from configuration
• integrate them into TransactionPluginRunner

However, after following the current implementation, I noticed that the remaining work extends beyond the host-side wrapper. The current TODO explains where a WasmPlugin should fit, but it doesn't yet define the contract between the Rust host and the Wasm guest.

I'd like to clarify the intended architecture so the implementation matches the long-term direction of the project rather than introducing an ABI that later needs to change.

---

Current implementation

Transaction plugin interface

kora/crates/lib/src/plugin/mod.rs

Lines 37 to 53 in e84bcab

	#[async_trait]
	trait TransactionPlugin: Send + Sync {
	async fn validate(
	&self,
	transaction: &mut VersionedTransactionResolved,
	_config: &Config,
	_rpc_client: &RpcClient,
	fee_payer: &Pubkey,
	context: PluginExecutionContext,
	) -> Result<(), KoraError>;
	/// Returns (errors, warnings) for this plugin's config requirements.
	/// Called at startup by the config validator.
	fn validate_config(&self, _config: &Config) -> (Vec<String>, Vec<String>) {
	(vec![], vec![])
	}
	}

This defines the current TransactionPlugin interface.

The trait currently receives:

• &mut VersionedTransactionResolved
• &Config
• &RpcClient
• &Pubkey
• PluginExecutionContext

This works naturally for native Rust plugins, but it raises questions for a Wasm guest because some of these values cannot cross the Wasm boundary directly.

---

Wasm TODO

kora/crates/lib/src/plugin/mod.rs

Lines 64 to 73 in e84bcab

	// TODO: WasmPlugin — operators should be able to register custom plugins via a config
	// path (e.g. `plugins = [{type = "wasm", path = "my_plugin.wasm"}]`) without requiring a
	// Kora source change or new release. A WasmPlugin implementing TransactionPlugin would
	// load a .wasm module at startup and call it for each transaction. The migration is clean:
	// WasmPlugin sits alongside typed built-ins until we're ready to drop hardcoded dispatch.
	//
	// pub struct WasmPlugin { engine: wasmtime::Engine, module: wasmtime::Module }
	// impl TransactionPlugin for WasmPlugin { ... }
	//
	// TransactionPluginType would gain a `Wasm { path: PathBuf }` variant alongside GasSwap.

The TODO clearly explains the desired direction:

• operator-provided Wasm plugins
• configuration-driven loading
• WasmPlugin
• wasmtime
• coexistence with existing built-in plugins

This provides the host-side direction, but it doesn't yet define the guest-side interface.

---

Current plugin construction

kora/crates/lib/src/plugin/mod.rs

Lines 74 to 90 in e84bcab

	for plugin in &config.kora.plugins.enabled {
	if !enabled.insert(plugin.clone()) {
	continue;
	}
	match plugin {
	TransactionPluginType::GasSwap => {
	plugins.push(Box::new(GasSwapPlugin));
	}
	TransactionPluginType::DeployAuthority => {
	plugins.push(Box::new(DeployAuthorityPlugin));
	}
	}
	}
	Self { plugins }
	}

Currently the runner constructs only built-in plugins through a fixed match.

This seems like the natural place where external plugins would eventually be integrated.

---

Configuration model

kora/crates/lib/src/config.rs

Lines 674 to 699 in e84bcab

	price_ttl: DEFAULT_CACHE_PRICE_TTL,
	}
	}
	}
	impl CacheConfig {
	/// Resolve the Redis URL to use. Priority: `KORA_REDIS_URL` env var over the `url`
	/// field from the TOML config. Returns `None` when neither is set.
	pub fn resolved_url(&self) -> Option<String> {
	std::env::var("KORA_REDIS_URL").ok().or_else(|| self.url.clone())
	}
	}
	#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, PartialEq, Eq, Hash)]
	#[serde(rename_all = "snake_case")]
	pub enum TransactionPluginType {
	GasSwap,
	DeployAuthority,
	}
	#[derive(Debug, Clone, Serialize, Deserialize, ToSchema, Default)]
	#[serde(default)]
	pub struct PluginsConfig {
	/// List of enabled transaction plugins, executed for sign/signAndSend flows
	pub enabled: Vec<TransactionPluginType>,
	}

Currently the configuration is limited to built-in plugin types.

Supporting external plugins will likely require extending this configuration model while keeping the current format backward compatible.

---

Configuration validation

kora/crates/lib/src/plugin/mod.rs

Lines 92 to 111 in e84bcab

	pub fn validate_config(config: &Config) -> (Vec<String>, Vec<String>) {
	let mut errors = Vec::new();
	let mut warnings = Vec::new();
	let mut seen = HashSet::new();
	for plugin_type in &config.kora.plugins.enabled {
	if !seen.insert(plugin_type.clone()) {
	continue;
	}
	let plugin: Box<dyn TransactionPlugin> = match plugin_type {
	TransactionPluginType::GasSwap => Box::new(GasSwapPlugin),
	TransactionPluginType::DeployAuthority => Box::new(DeployAuthorityPlugin),
	};
	let (e, w) = plugin.validate_config(config);
	errors.extend(e);
	warnings.extend(w);
	}
	(errors, warnings)
	}

and

kora/crates/lib/src/validator/config_validator.rs

Lines 586 to 602 in e84bcab

	if config.kora.sign_max_retries > HIGH_SIGN_MAX_RETRIES_WARNING_THRESHOLD {
	warnings.push(format!(
	"sign_max_retries ({}) is very high - consider reducing to prevent long request hangs",
	config.kora.sign_max_retries
	));
	}
	let mut unique_plugins = std::collections::HashSet::new();
	for plugin in &config.kora.plugins.enabled {
	if !unique_plugins.insert(plugin.clone()) {
	warnings.push(format!("Duplicate transaction plugin configured: {:?}", plugin));
	}
	}
	let (plugin_errors, plugin_warnings) = TransactionPluginRunner::validate_config(config);
	errors.extend(plugin_errors);
	warnings.extend(plugin_warnings);

The existing validation flow already provides a natural place for plugin-specific validation.

---

Existing plugin examples

GasSwap:

https://github.com/solana-foundation/kora/blob/e84bcaba4532135af941cd4654c3bb3a100ad2b7/crates/lib/src/plugin/plugin_gas_swap.rs

DeployAuthority:

https://github.com/solana-foundation/kora/blob/e84bcaba4532135af941cd4654c3bb3a100ad2b7/crates/lib/src/plugin/plugin_deploy_authority.rs

One interesting observation is that DeployAuthorityPlugin depends on RpcClient for on-chain lookups, while GasSwapPlugin performs only local validation.

That difference made me wonder what the intended capabilities of a Wasm plugin are expected to be.

---

Questions

While exploring the implementation, I wasn't able to determine the intended Wasm ABI.

Some questions came up:

1. Should a Wasm plugin expose a single validation entry point, or is another interface expected?

2. Is the intention for Wasm plugins to support transaction mutation, or should they only perform validation?

3. How should a Wasm plugin perform operations that currently rely on RpcClient (for example, logic similar to DeployAuthorityPlugin)?

4. Is there an intended serialization format between the host and the guest?

5. Is wasmtime still the preferred runtime, or was it simply used as an example in the TODO?

6. Would it make sense to define a small ABI/interface document before implementing the runtime?

[JuanTorchia]

@raushan728 — not a maintainer, so the intent questions aren't mine to answer.
But I read the plugin path and built a throwaway wasmtime host to see what (3)
and (4) cost in practice, and some of it narrows the space.

(2) is the one I'd settle first, and it turns out to be an ordering question
rather than an ABI one: the plugin runs after validate_transaction, and a
plugin that writes through the &mut reaches the signed message without
fee_payer_policy being re-checked. That holds today with the built-ins, so
rather than pile it onto your thread I've sent it to the maintainers through the
advisory channel — it isn't exploitable as things stand, the trait is private and
there's no external loader, but SECURITY.md is clear about not opening an issue
first and it's their call where it belongs. I'll link it here if it becomes a
public issue. It matters for your question because an ABI mirroring the trait
signature hands that same write capability to operator-supplied modules, where it
wouldn't be a matter of trusting two in-tree built-ins.

(3) — the two built-ins between them need one host function. GasSwapPlugin
never uses its rpc_client binding (plugin_gas_swap.rs:113);
DeployAuthorityPlugin calls get_account_with_commitment once (:43-44). I
wouldn't read the long-term surface off that, though: the underscores were in the
trait from the first plugin commit, so the client was provisioned ahead of need.
Gas-swap validates the shape of "SPL in, SOL out" and never compares amounts, and
a price isn't an account read — it comes from Jupiter over HTTP
(oracle/jupiter.rs). A guest also gets no clock and no logging unless the host
links one, which the Rust trait gets for free. So capabilities declared at
validate_config time rather than a fixed count — which is also what would let
the host parse only what a module asked for, instead of all six sets on the
signing path.

(4) — you can pass a handle (externref), but the guest can't dereference it,
so bytes get copied either way. Two directions worth separating. Inbound, the
host copies the view into guest linear memory through an allocator the guest
exports. Outbound is the part I'd get right first: a bare verdict throws away
what the built-ins produce — five distinct InvalidTransaction messages in
GasSwap, twenty-one in DeployAuthority, most interpolating pubkeys. I first had
the guest return a packed (ptr << 32) | len, which is wrong: the host then
allocates at a length the guest chose, and a hostile module returning
0xffffffff gets 4 GiB reserved before the bounds check fires. Having the guest
push the message through a host_reject(ptr, len) import instead lets the host
clamp and copy immediately, and nothing of the guest's outlives the call. Worth
saying this is a partial, ownership-less version of what the component model's
canonical ABI already specifies, post-return dealloc included — which is most of
why (6)'s real fork is core module vs. component model.

What the spike measured, since the numbers changed my mind on the deadline
story:

8 host reads at 200ms each    1.609s wall, 785 fuel of 5,000,000
pure guest loop, fuel on      OutOfFuel trap, ~300µs
same loop, 100ms epoch tick   Interrupt trap at 100.1ms

Fuel bounds compute and doesn't bound host time at all — 785 units for 1.6s of
wall clock — so the read limit caps the dominant term rather than being the cheap
knob I'd assumed. (The fuel figure is identical run to run, which is the
determinism argument for fuel over epoch; the µs number isn't, don't read
anything into it.) A caveat I didn't measure: the epoch deadline does nothing on
its own — something has to call Engine::increment_epoch() on a cadence, and the
docs say as much, with Engine::weak() in the ticker so it doesn't keep the
engine alive. And Store is per-request, not because it isn't Send but
because every entrypoint takes &mut and a store never releases memory back:
Engine and Module once at startup, Linker::instantiate_pre once, Store
per transaction. Worth noting from_config (plugin/mod.rs:60-90) is called
inside sign_transaction at versioned_transaction.rs:416, so a WasmPlugin
constructed in that match would be built per signing request.

Three things I'd want decided before writing a guest, none of them ABI shape.
Whether a trapping plugin fails the request or is skipped — in a signing path
that has to be fail-closed, and a guest that returns "reject" without supplying a
reason needs the same default. Where the module comes from: Module::from_file
on a .wasm is validated, but Module::deserialize on a cached artifact is
unsafe and its docs say arbitrary input there is arbitrary code execution, so a
path in kora.toml wants a pinned hash next to it. And max_wasm_stack against
async_stack_size — mis-sized, deep guest recursion aborts the process rather
than trapping, which with async_support is the difference between rejecting a
transaction and killing the node that signs.

Happy to push the spike to a gist. I'm not going to open a PR on the ABI — it's
your issue and the sketch is yours if you want it; I'd rather hand you the
material.

---

On AI use, per CONTRIBUTING.md: I directed this and checked every line
reference and claim against the source myself; Claude did the code reading, built
the throwaway wasmtime host, and drafted the write-up.