aios_protocol/
payment.rs

1//! Payment port — canonical interface for agent financial operations.
2//!
3//! This module defines the `PaymentPort` trait and associated types that
4//! form the boundary between the Agent OS kernel and payment implementations
5//! (x402, MPP, etc.). Implementations live in the Haima project.
6
7use crate::error::KernelResult;
8use crate::ids::SessionId;
9use async_trait::async_trait;
10use serde::{Deserialize, Serialize};
11
12/// A payment authorization request from the agent runtime.
13#[derive(Debug, Clone, Serialize, Deserialize)]
14pub struct PaymentAuthorizationRequest {
15    /// Session requesting the payment.
16    pub session_id: SessionId,
17    /// URL of the resource requiring payment.
18    pub resource_url: String,
19    /// Amount in micro-credits (1 credit = 1,000,000 micro-credits).
20    pub amount_micro_credits: i64,
21    /// Token symbol (e.g., "USDC").
22    pub token: String,
23    /// Chain identifier in CAIP-2 format (e.g., "eip155:8453").
24    pub chain: String,
25    /// Recipient address.
26    pub recipient: String,
27    /// Human-readable description.
28    pub description: Option<String>,
29}
30
31/// The result of a payment authorization evaluation.
32#[derive(Debug, Clone, Serialize, Deserialize)]
33#[serde(tag = "decision", rename_all = "snake_case")]
34pub enum PaymentAuthorizationDecision {
35    /// Payment approved — proceed with signing and settlement.
36    Approved {
37        /// Micro-credits that will be deducted.
38        amount_micro_credits: i64,
39    },
40    /// Payment requires human approval via ApprovalPort.
41    RequiresApproval {
42        /// Why approval is needed.
43        reason: String,
44    },
45    /// Payment denied by policy.
46    Denied {
47        /// Why the payment was denied.
48        reason: String,
49    },
50}
51
52/// Settlement receipt from an on-chain payment.
53#[derive(Debug, Clone, Serialize, Deserialize)]
54pub struct PaymentSettlementReceipt {
55    /// Transaction hash on the target chain.
56    pub tx_hash: String,
57    /// Chain where settlement occurred.
58    pub chain: String,
59    /// Amount in micro-credits.
60    pub amount_micro_credits: i64,
61    /// Settlement latency in milliseconds.
62    pub latency_ms: u64,
63}
64
65/// Agent wallet balance information.
66#[derive(Debug, Clone, Serialize, Deserialize)]
67pub struct WalletBalanceInfo {
68    /// Wallet address.
69    pub address: String,
70    /// Chain identifier.
71    pub chain: String,
72    /// On-chain balance in micro-credits.
73    pub on_chain_micro_credits: i64,
74    /// Internal ledger balance in micro-credits.
75    pub internal_micro_credits: i64,
76}
77
78/// The canonical payment port — the only allowed boundary between the kernel
79/// and payment implementations.
80///
81/// Implementations:
82/// - `haima-x402`: x402 protocol (Coinbase/Cloudflare)
83/// - Future: MPP (Stripe/Tempo), direct fiat rails
84#[async_trait]
85pub trait PaymentPort: Send + Sync {
86    /// Evaluate whether a payment should be authorized given current policy
87    /// and economic state.
88    async fn authorize(
89        &self,
90        request: PaymentAuthorizationRequest,
91    ) -> KernelResult<PaymentAuthorizationDecision>;
92
93    /// Execute a pre-authorized payment (sign and submit to facilitator).
94    async fn settle(
95        &self,
96        request: PaymentAuthorizationRequest,
97    ) -> KernelResult<PaymentSettlementReceipt>;
98
99    /// Query the agent's wallet balance.
100    async fn balance(&self) -> KernelResult<WalletBalanceInfo>;
101}
aios_protocol/payment.rs

aios_protocol/
payment.rs
