The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! OpenHuman's typed host callbacks for the loadable TinyWallet module.
//!
//! The wallet module owns network/quote/payment algorithms and signing. This
//! service supplies only current public account facts, endpoint-backed chain
//! transport, authenticated wallet-backend transport, and a confirmation
//! decision bound to an in-flight confirmed execution request.
use crate::core::runtime::DispatchCtx;
use std::collections::{HashMap, HashSet};
use std::future::Future;
use std::sync::{Mutex, OnceLock};
use tinybus::ObjectPath;
use tinywallet_bus::wire::HostEndpointReference;
use tinywallet_bus::wire::{
AuthorizationResult, AuthorizeNativeWalletExecutionRequest, AuthorizeWeb3ExecutionRequest,
AuthorizeX402PaymentRequest, ChainTransportRequest, ChainTransportResult, HostResponse,
RpcEndpointKey, WalletAccountInfo, WalletAccountsResponse, WalletBackendRequest,
WalletBackendResponse,
};
#[path = "wallet_host_transport.rs"]
mod transport;
use transport::{
classify_transport_error, endpoint_key, join_endpoint, validate_module_endpoint_url,
TransportFailure,
};
const HOST_ERROR_NAME: &str = "ai.tinyhumans.tinywallet.Host.Error.CallbackFailed";
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub(crate) enum ApprovalKind {
Native,
Web3,
}
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
struct ApprovalKey {
kind: ApprovalKind,
quote_id: String,
}
static APPROVALS: OnceLock<Mutex<HashSet<ApprovalKey>>> = OnceLock::new();
static NATIVE_APPROVAL_QUOTES: OnceLock<
Mutex<HashMap<String, tinywallet_bus::wire::PreparedTransaction>>,
> = OnceLock::new();
static WEB3_APPROVAL_QUOTES: OnceLock<
Mutex<HashMap<String, tinywallet_bus::wire::Web3QuoteResponse>>,
> = OnceLock::new();
static ENDPOINT_REFERENCES: OnceLock<Mutex<HashMap<String, EndpointReference>>> = OnceLock::new();
#[derive(Debug, Clone)]
struct EndpointReference {
service: String,
key: RpcEndpointKey,
}
fn approvals() -> &'static Mutex<HashSet<ApprovalKey>> {
APPROVALS.get_or_init(|| Mutex::new(HashSet::new()))
}
fn native_approval_quotes(
) -> &'static Mutex<HashMap<String, tinywallet_bus::wire::PreparedTransaction>> {
NATIVE_APPROVAL_QUOTES.get_or_init(|| Mutex::new(HashMap::new()))
}
fn web3_approval_quotes() -> &'static Mutex<HashMap<String, tinywallet_bus::wire::Web3QuoteResponse>>
{
WEB3_APPROVAL_QUOTES.get_or_init(|| Mutex::new(HashMap::new()))
}
fn endpoint_references() -> &'static Mutex<HashMap<String, EndpointReference>> {
ENDPOINT_REFERENCES.get_or_init(|| Mutex::new(HashMap::new()))
}
/// Whether the payment was quoted for the chat the acting turn is in.
///
/// An x402 payment is approved with a forced approval, which only a `WebChat`
/// turn can raise, and that origin carries the same thread and client the turn's
/// chat context does. The origin is therefore the chat to compare against; the
/// callback arrives over the bus with no run context of its own.
fn x402_request_owner_matches(
request: &AuthorizeX402PaymentRequest,
origin: Option<&crate::security::turn_origin::AgentTurnOrigin>,
) -> bool {
let Some(crate::security::turn_origin::AgentTurnOrigin::WebChat {
thread_id,
client_id,
..
}) = origin
else {
return false;
};
request
.owner
.as_ref()
.is_some_and(|owner| &owner.thread_id == thread_id && &owner.client_id == client_id)
}
fn x402_approval_facts(request: &AuthorizeX402PaymentRequest) -> serde_json::Value {
serde_json::json!({
"url": request.url,
"network": request.network,
"asset": request.asset,
"recipient": request.recipient,
"amount_atomic": request.amount_atomic,
})
}
/// Bind module-issued opaque endpoint aliases to the current host configuration.
/// Actual URLs remain in this process and are never serialized onto TinyBus.
pub(crate) fn bind_endpoint_references(
service: &str,
references: &[HostEndpointReference],
) -> Result<(), String> {
let mut resolved = HashMap::new();
for endpoint in references {
// Validate admission here, but resolve the URL again on each callback:
// the host may rotate an endpoint override without changing its opaque
// module reference.
configured_endpoint_url(endpoint.key)
.map_err(|_| "wallet module referenced an endpoint without a host override")?;
if endpoint.reference.trim().is_empty()
|| resolved
.insert(
endpoint.reference.clone(),
EndpointReference {
service: service.to_owned(),
key: endpoint.key,
},
)
.is_some()
{
return Err("wallet module returned an invalid endpoint reference".into());
}
}
endpoint_references()
.lock()
.map_err(|_| "wallet endpoint reference store is unavailable".to_string())?
.extend(resolved);
Ok(())
}
fn configured_endpoint_url(key: RpcEndpointKey) -> Result<String, String> {
let url = crate::web3::wallet::endpoints::override_for_endpoint(key)
.ok_or_else(|| "wallet endpoint override is no longer configured".to_string())?;
validate_module_endpoint_url(&url)
}
pub(crate) fn clear_endpoint_references(service: &str) {
if let Ok(mut references) = endpoint_references().lock() {
references.retain(|_, endpoint| endpoint.service != service);
}
}
#[cfg(test)]
pub(super) fn has_endpoint_reference_for_test(reference: &str) -> bool {
endpoint_references()
.lock()
.is_ok_and(|references| references.contains_key(reference))
}
pub(crate) async fn wallet_accounts_snapshot(
ctx: &DispatchCtx,
) -> Result<tinywallet_bus::wire::WalletAccountsResponse, String> {
let status = crate::web3::wallet::status(ctx)
.await
.map_err(|error| error.to_string())?
.value;
let accounts = status
.accounts
.into_iter()
.map(|account| WalletAccountInfo {
chain: account.chain.to_chain(),
address: account.address,
derivation_path: account.derivation_path,
})
.collect();
Ok(WalletAccountsResponse {
configured: status.configured,
accounts,
})
}
/// One-shot authorization permit for an execution whose public RPC request
/// already carried `confirmed: true`.
struct ApprovalPermit(ApprovalKey);
impl ApprovalPermit {
fn new(
kind: ApprovalKind,
quote_id: &str,
expected_native_quote: Option<tinywallet_bus::wire::PreparedTransaction>,
expected_web3_quote: Option<tinywallet_bus::wire::Web3QuoteResponse>,
) -> Self {
let key = ApprovalKey {
kind,
quote_id: quote_id.to_owned(),
};
if let Ok(mut active) = approvals().lock() {
active.insert(key.clone());
}
if kind == ApprovalKind::Native {
if let (Some(quote), Ok(mut active)) =
(expected_native_quote, native_approval_quotes().lock())
{
active.insert(quote_id.to_owned(), quote);
}
}
if kind == ApprovalKind::Web3 {
if let (Some(quote), Ok(mut active)) =
(expected_web3_quote, web3_approval_quotes().lock())
{
active.insert(quote_id.to_owned(), quote);
}
}
Self(key)
}
}
impl Drop for ApprovalPermit {
fn drop(&mut self) {
if let Ok(mut active) = approvals().lock() {
active.remove(&self.0);
}
if self.0.kind == ApprovalKind::Native {
if let Ok(mut active) = native_approval_quotes().lock() {
active.remove(&self.0.quote_id);
}
}
if self.0.kind == ApprovalKind::Web3 {
if let Ok(mut active) = web3_approval_quotes().lock() {
active.remove(&self.0.quote_id);
}
}
}
}
fn consume_approval(kind: ApprovalKind, quote_id: &str) -> bool {
approvals().lock().is_ok_and(|mut active| {
active.remove(&ApprovalKey {
kind,
quote_id: quote_id.to_owned(),
})
})
}
pub(super) fn native_approval_matches_request(
expected_quote: &tinywallet_bus::wire::PreparedTransaction,
request: &tinywallet_bus::wire::AuthorizeNativeWalletExecutionRequest,
) -> bool {
let permit = consume_approval(ApprovalKind::Native, &request.quote_id);
permit
&& expected_quote.quote_id == request.quote_id
&& expected_quote == &request.quote
&& request.operation == "transfer"
&& native_intent_matches_quote(expected_quote, &request.intent)
}
fn web3_approval_matches_request(
quote: &tinywallet_bus::wire::Web3QuoteResponse,
request: &AuthorizeWeb3ExecutionRequest,
) -> bool {
use tinywallet_bus::wire::{WalletChain, Web3ExecutionIntent, Web3QuoteKind};
let operation_matches = matches!(
(quote.kind, request.operation.as_str()),
(Web3QuoteKind::Swap, "swap")
| (Web3QuoteKind::Bridge, "bridge")
| (Web3QuoteKind::DappCall, "dapp_call")
);
if quote.quote_id != request.quote_id || !operation_matches {
return false;
}
match (&request.transaction, quote.signing_chain) {
(
Web3ExecutionIntent::Evm {
network,
to,
data,
value,
chain_id,
..
},
WalletChain::Evm,
) => {
let expected_network = quote
.quote
.get("network")
.and_then(serde_json::Value::as_str);
if expected_network.is_some_and(|expected| expected != network)
|| !known_evm_chain(network, *chain_id)
{
return false;
}
let transaction = quote.quote.get("tx");
match quote.kind {
Web3QuoteKind::DappCall => {
let expected_to = quote
.quote
.get("contractAddress")
.and_then(serde_json::Value::as_str);
let expected_data = quote
.quote
.get("calldata")
.and_then(serde_json::Value::as_str);
let expected_value = quote
.quote
.get("valueRaw")
.and_then(serde_json::Value::as_str);
expected_to.is_some_and(|expected| expected.eq_ignore_ascii_case(to))
&& expected_data.is_some_and(|expected| data.as_deref() == Some(expected))
&& expected_value.is_some_and(|expected| expected == value)
}
Web3QuoteKind::Swap | Web3QuoteKind::Bridge => {
transaction.is_some_and(|transaction| {
transaction
.get("to")
.and_then(serde_json::Value::as_str)
.is_some_and(|expected| expected.eq_ignore_ascii_case(to))
&& transaction.get("data").and_then(serde_json::Value::as_str)
== data.as_deref()
&& decimal_json(transaction.get("value")).as_deref()
== Some(value.as_str())
})
}
}
}
(Web3ExecutionIntent::Solana { tx_blob_hex }, WalletChain::Solana) => {
let expected = quote
.quote
.get("tx")
.and_then(|transaction| transaction.get("data"))
.and_then(serde_json::Value::as_str);
matches!(quote.kind, Web3QuoteKind::Swap | Web3QuoteKind::Bridge)
&& expected == Some(tx_blob_hex.as_str())
}
_ => false,
}
}
fn known_evm_chain(network: &str, chain_id: u64) -> bool {
tinywallet_bus::wire::EvmNetwork::ALL
.into_iter()
.any(|known| known.as_str() == network && known.chain_id() == chain_id)
}
fn decimal_json(value: Option<&serde_json::Value>) -> Option<String> {
match value? {
serde_json::Value::String(value) => Some(value.clone()),
serde_json::Value::Number(value) => Some(value.to_string()),
_ => None,
}
}
fn native_intent_matches_quote(
quote: &tinywallet_bus::wire::PreparedTransaction,
intent: &tinywallet_bus::wire::NativeWalletExecutionIntent,
) -> bool {
use tinywallet_bus::wire::{
NativeWalletExecutionIntent, PreparedKind, TransactionSpec, WalletChain,
};
match intent {
NativeWalletExecutionIntent::Transaction { transaction } => match transaction {
TransactionSpec::Btc {
from,
to,
amount_sat,
..
} => {
quote.chain == WalletChain::Btc
&& quote.kind == PreparedKind::NativeTransfer
&& from == "e.from_address
&& to == "e.to_address
&& quote.amount_raw.parse::<u64>().ok() == Some(*amount_sat)
}
TransactionSpec::Evm {
to,
value_wei,
data_hex,
chain_id,
..
} => {
let network = quote
.evm_network
.unwrap_or(tinywallet_bus::wire::EvmNetwork::EthereumMainnet);
if quote.chain != WalletChain::Evm || network.chain_id() != *chain_id {
return false;
}
match quote.kind {
PreparedKind::NativeTransfer => {
to == "e.to_address
&& value_wei == "e.amount_raw
&& data_hex.is_empty()
}
PreparedKind::TokenTransfer => {
let Some(contract) = quote.token_address.as_deref() else {
return false;
};
to.eq_ignore_ascii_case(contract)
&& value_wei == "0"
&& evm_transfer_data_matches(
data_hex,
"e.to_address,
"e.amount_raw,
)
}
}
}
TransactionSpec::Solana {
from, to, lamports, ..
} => {
quote.chain == WalletChain::Solana
&& quote.kind == PreparedKind::NativeTransfer
&& from == "e.from_address
&& to == "e.to_address
&& quote.amount_raw.parse::<u64>().ok() == Some(*lamports)
}
TransactionSpec::Tron {
expected_to,
transfer,
..
} => {
use tinywallet_bus::TronTransfer;
if quote.chain != WalletChain::Tron || expected_to != "e.to_address {
return false;
}
match (quote.kind, transfer) {
(PreparedKind::NativeTransfer, TronTransfer::Native { amount_sun }) => {
quote.amount_raw.parse::<u64>().ok() == Some(*amount_sun)
}
(PreparedKind::TokenTransfer, TronTransfer::Trc20 { parameter_hex }) => {
valid_hex(parameter_hex)
}
_ => false,
}
}
_ => false,
},
NativeWalletExecutionIntent::SolanaMessage { message_hex } => {
quote.chain == WalletChain::Solana
&& quote.kind == PreparedKind::TokenTransfer
&& valid_hex(message_hex)
}
}
}
fn evm_transfer_data_matches(data: &str, recipient: &str, amount: &str) -> bool {
let Some(address) = recipient
.strip_prefix("0x")
.or_else(|| recipient.strip_prefix("0X"))
else {
return false;
};
if address.len() != 40 || !address.bytes().all(|byte| byte.is_ascii_hexdigit()) {
return false;
}
let Some(amount_word) = decimal_u256_word(amount) else {
return false;
};
let expected = format!("a9059cbb{:0>64}{amount_word}", address.to_ascii_lowercase());
let actual = data
.strip_prefix("0x")
.or_else(|| data.strip_prefix("0X"))
.unwrap_or(data);
actual.eq_ignore_ascii_case(&expected)
}
fn decimal_u256_word(decimal: &str) -> Option<String> {
if decimal.is_empty() || !decimal.bytes().all(|byte| byte.is_ascii_digit()) {
return None;
}
let mut bytes = [0u8; 32];
for digit in decimal.bytes().map(|byte| byte - b'0') {
let mut carry = u16::from(digit);
for byte in bytes.iter_mut().rev() {
let value = u16::from(*byte) * 10 + carry;
*byte = (value & 0xff) as u8;
carry = value >> 8;
}
if carry != 0 {
return None;
}
}
Some(bytes.iter().map(|byte| format!("{byte:02x}")).collect())
}
fn valid_hex(value: &str) -> bool {
!value.is_empty()
&& value.len().is_multiple_of(2)
&& value.bytes().all(|byte| byte.is_ascii_hexdigit())
}
/// Keep the confirmation permit alive only while the corresponding module
/// execution is in flight. The callback consumes it once and is correlated by
/// the immutable module-issued quote id.
pub(crate) async fn with_confirmed_execution<F: Future>(
kind: ApprovalKind,
quote_id: &str,
expected_native_quote: Option<tinywallet_bus::wire::PreparedTransaction>,
expected_web3_quote: Option<tinywallet_bus::wire::Web3QuoteResponse>,
future: F,
) -> F::Output {
let _permit = ApprovalPermit::new(kind, quote_id, expected_native_quote, expected_web3_quote);
future.await
}
#[derive(Clone, Copy)]
struct WalletHost;
#[tinybus::interface(name = "ai.tinyhumans.tinywallet.Host")]
impl WalletHost {
/// Public wallet setup state and addresses; encrypted secrets never leave
/// the host's custody store through this callback.
async fn wallet_accounts(&self) -> tinybus::Result<HostResponse> {
Ok(HostResponse::WalletAccounts(
wallet_accounts_snapshot(&DispatchCtx::host_default())
.await
.map_err(callback_error)?,
))
}
/// Run the chain operation through OpenHuman's configured RPC transport.
async fn chain_transport(
&self,
request: ChainTransportRequest,
) -> tinybus::Result<HostResponse> {
let (endpoint_ref, module_endpoint_url, chain, evm_chain_id) = match &request {
ChainTransportRequest::JsonRpc { network, .. }
| ChainTransportRequest::RestGet { network, .. }
| ChainTransportRequest::RestPost { network, .. } => (
network.endpoint_ref.as_deref(),
network.endpoint_url.as_deref(),
network.chain,
network.evm_chain_id,
),
};
let endpoint_url = match (endpoint_ref, module_endpoint_url) {
(Some(_), Some(_)) => {
return Ok(HostResponse::ChainTransport(
ChainTransportResult::RpcError {
message: "wallet request cannot combine an endpoint reference and URL"
.into(),
},
));
}
(Some(reference), None) => {
let Some(endpoint) = endpoint_references()
.lock()
.ok()
.and_then(|references| references.get(reference).cloned())
else {
return Ok(HostResponse::ChainTransport(
ChainTransportResult::RpcError {
message:
"the requested wallet endpoint reference is not active in this host"
.into(),
},
));
};
if Some(endpoint.key) != endpoint_key(chain, evm_chain_id) {
return Ok(HostResponse::ChainTransport(
ChainTransportResult::RpcError {
message:
"the wallet endpoint reference does not match the requested network"
.into(),
},
));
}
match configured_endpoint_url(endpoint.key) {
Ok(url) => url,
Err(message) => {
return Ok(HostResponse::ChainTransport(
ChainTransportResult::RpcError { message },
));
}
}
}
(None, Some(url)) => match validate_module_endpoint_url(url) {
Ok(url) => url,
Err(message) => {
return Ok(HostResponse::ChainTransport(
ChainTransportResult::RpcError { message },
));
}
},
(None, None) => {
return Ok(HostResponse::ChainTransport(
ChainTransportResult::RpcError {
message: "wallet module did not select an RPC endpoint".into(),
},
));
}
};
let result = match request {
ChainTransportRequest::JsonRpc { method, params, .. } => {
crate::web3::wallet::rpc::rpc_call_to::<serde_json::Value>(
&endpoint_url,
&method,
params,
)
.await
.map_err(classify_transport_error)
}
ChainTransportRequest::RestGet { path, .. } => {
crate::web3::wallet::rpc::rest_get_text(&join_endpoint(&endpoint_url, &path))
.await
.map(serde_json::Value::String)
.map_err(classify_transport_error)
}
ChainTransportRequest::RestPost {
path,
body,
content_type,
..
} => crate::web3::wallet::rpc::rest_post_text(
&join_endpoint(&endpoint_url, &path),
&body,
&content_type,
)
.await
.map(serde_json::Value::String)
.map_err(classify_transport_error),
};
let response = match result {
Ok(body) => ChainTransportResult::Ok { body },
Err(TransportFailure::Unreachable(message)) => {
ChainTransportResult::Unreachable { message }
}
Err(TransportFailure::Rpc(message)) => ChainTransportResult::RpcError { message },
};
Ok(HostResponse::ChainTransport(response))
}
/// Perform only the named authenticated wallet-backend request.
async fn wallet_backend(&self, request: WalletBackendRequest) -> tinybus::Result<HostResponse> {
let config = DispatchCtx::host_default()
.load_config()
.await
.map_err(callback_error)?;
let data = super::wallet_backend::call_wallet_backend(config, request.into())
.await
.map_err(callback_error)?;
Ok(HostResponse::WalletBackend(WalletBackendResponse { data }))
}
/// A module callback is permitted only while the host is servicing the
/// exact confirmed quote id. The module supplies the transaction intent
/// built from its stored quote; the host never constructs or signs it.
async fn authorize_web3_execution(
&self,
request: AuthorizeWeb3ExecutionRequest,
) -> tinybus::Result<HostResponse> {
let quote = web3_approval_quotes()
.lock()
.ok()
.and_then(|mut quotes| quotes.remove(&request.quote_id));
Ok(HostResponse::Authorization(AuthorizationResult {
approved: quote
.as_ref()
.is_some_and(|quote| web3_approval_matches_request(quote, &request))
&& consume_approval(ApprovalKind::Web3, &request.quote_id),
reason: None,
}))
}
/// Approve the exact native quote facts only inside the corresponding
/// confirmed host operation.
async fn authorize_native_wallet_execution(
&self,
request: AuthorizeNativeWalletExecutionRequest,
) -> tinybus::Result<HostResponse> {
let expected = native_approval_quotes()
.lock()
.ok()
.and_then(|mut quotes| quotes.remove(&request.quote_id));
let approved = expected
.as_ref()
.is_some_and(|quote| native_approval_matches_request(quote, &request));
Ok(HostResponse::Authorization(AuthorizationResult {
approved,
reason: None,
}))
}
/// x402 authorization is supplied by the host's guarded HTTP request path;
/// absent an active guard scope, payment signing fails closed.
async fn authorize_x402_payment(
&self,
request: AuthorizeX402PaymentRequest,
) -> tinybus::Result<HostResponse> {
let origin = crate::core::runtime::DispatchCtx::ambient_turn().turn_origin();
let owner_matches = x402_request_owner_matches(&request, origin.as_ref());
let approved = if owner_matches {
if let Some(gate) = crate::security::approval::ApprovalGate::try_global() {
matches!(
gate.intercept_forced(
"x402_payment",
"Approve this exact x402 payment",
x402_approval_facts(&request),
)
.await,
crate::security::approval::GateOutcome::Allow
)
} else {
false
}
} else {
false
};
Ok(HostResponse::Authorization(AuthorizationResult {
approved,
reason: (!approved)
.then(|| "x402 payment was not explicitly approved for this chat".into()),
}))
}
}
fn callback_error(error: impl std::fmt::Display) -> tinybus::Error {
tinybus::Error::MethodFailed {
name: HOST_ERROR_NAME.to_string(),
message: error.to_string(),
}
}
/// Install the host callback interface before any TinyWallet module can load.
pub(super) async fn install(connection: &tinybus::Connection) -> tinybus::Result<()> {
connection
.serve_at(
ObjectPath::new(tinywallet_bus::HOST_OBJECT_PATH)?,
WalletHost,
)
.await?;
connection
.request_name(tinywallet_bus::HOST_INTERFACE)
.await
}
#[cfg(test)]
#[path = "wallet_host_tests.rs"]
mod tests;