x402_core/
core.rs

1//! Core traits and types used across the X402 Kit.
2
3use std::{fmt::Display, str::FromStr};
4
5use bon::Builder;
6use url::Url;
7
8use crate::types::{AmountValue, AnyJson, Extension, OutputSchema, Record};
9
10/// A series of network families, e.g. EVM, SVM, etc.
11pub trait NetworkFamily {
12    /// The name of the network in the family, should be compatible with X402 V1.
13    fn network_name(&self) -> &str;
14
15    /// The Blockchain network identifier in CAIP-2 format (e.g., "eip155:84532")
16    fn network_id(&self) -> &str;
17}
18
19/// Network-specific address type.
20pub trait Address: FromStr + Display + Copy {
21    /// The network family this address belongs to.
22    type Network: NetworkFamily;
23}
24
25/// A payment scheme applied to a network family.
26pub trait Scheme {
27    /// The network family this scheme applies to.
28    type Network: NetworkFamily;
29    /// The payload type produced by this scheme.
30    type Payload;
31    /// The name of the scheme.
32    const SCHEME_NAME: &'static str;
33    /// Get the concrete network for this scheme.
34    fn network(&self) -> &Self::Network;
35}
36
37/// Represents an asset on a given address.
38#[derive(Debug, Clone, Copy, PartialEq, Eq)]
39pub struct Asset<A: Address> {
40    pub address: A,
41    pub decimals: u8,
42    pub name: &'static str,
43    pub symbol: &'static str,
44}
45
46/// Payment configuration for a given scheme and transport.
47#[derive(Builder)]
48pub struct Payment<S, A>
49where
50    S: Scheme,
51    A: Address<Network = S::Network>,
52{
53    /// The payment scheme.
54    pub scheme: S,
55    /// The address to use for payments.
56    #[builder(into)]
57    pub pay_to: A,
58    /// The asset for the payment
59    #[builder(into)]
60    pub asset: Asset<A>,
61    /// The amount of the asset to pay, in smallest units.
62    #[builder(into)]
63    pub amount: AmountValue,
64    /// Maximum timeout in seconds for the payment to be completed.
65    pub max_timeout_seconds: u64,
66    /// Optional extra data for the payment.
67    pub extra: Option<AnyJson>,
68}
69
70/// The selected payment for the signer to sign.
71///
72/// Selected payment only knows about the asset's address, not full asset details.
73#[derive(Builder)]
74pub struct PaymentSelection<A: Address> {
75    /// The address to use for payments.
76    #[builder(into)]
77    pub pay_to: A,
78    /// The asset for the payment
79    #[builder(into)]
80    pub asset: A,
81    /// The amount of the asset to pay, in smallest units.
82    #[builder(into)]
83    pub amount: AmountValue,
84    /// Maximum timeout in seconds for the payment to be completed.
85    pub max_timeout_seconds: u64,
86    /// Optional extra data for the payment.
87    pub extra: Option<AnyJson>,
88    /// Resource definition.
89    pub resource: Resource,
90    /// Extensions
91    #[builder(default)]
92    pub extensions: Record<Extension>,
93}
94
95/// Signer for a given payment scheme.
96pub trait SchemeSigner<A: Address<Network = <Self::Scheme as Scheme>::Network>> {
97    type Scheme: Scheme;
98    type Error: std::error::Error;
99
100    fn sign(
101        &self,
102        payment: &PaymentSelection<A>,
103    ) -> impl Future<Output = Result<<Self::Scheme as Scheme>::Payload, Self::Error>>;
104}
105
106/// Resource definition.
107#[derive(Builder, Debug, Clone, PartialEq, Eq)]
108pub struct Resource {
109    /// Optional resource URL.
110    pub url: Url,
111    /// Optional description of the resource.
112    #[builder(into)]
113    pub description: String,
114    /// Optional MIME type of the resource.
115    #[builder(into)]
116    pub mime_type: String,
117    /// Optional output schema for the payment payload.
118    pub output_schema: Option<OutputSchema>,
119}
x402_core/core.rs

x402_core/
core.rs
