r402-extensions 0.21.0

Protocol extension implementations for the x402 payment protocol.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95

//! Server advertise helper for `erc20ApprovalGasSponsoring` (official wire).
//!
//! Client signed-tx payload types live in `r402-evm`. This module only
//! declares the extension on `PaymentRequired` for resource servers.

use r402_protocol::extension::{AdvertiseContext, Extension};
use r402_protocol::payment::ExtensionEntry;
use serde_json::{Value, json};

/// Stable extension key on the wire.
pub const ERC20_APPROVAL_GAS_SPONSORING_KEY: &str = "erc20ApprovalGasSponsoring";

/// Current schema version for server advertise info.
pub const ERC20_APPROVAL_GAS_SPONSORING_VERSION: &str = "1";

/// Official client `info` JSON Schema (from `erc20_gas_sponsoring.md`).
fn client_info_schema() -> Value {
    json!({
        "$schema": "https://json-schema.org/draft/2020-12/schema",
        "type": "object",
        "properties": {
            "from": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
            "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
            "spender": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
            "amount": { "type": "string", "pattern": "^[0-9]+$" },
            "signedTransaction": { "type": "string", "pattern": "^0x[a-fA-F0-9]+$" },
            "version": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]+)*$" }
        },
        "required": ["from", "asset", "spender", "amount", "signedTransaction", "version"]
    })
}

/// Resource-server declaration of ERC-20 approval gas sponsoring support.
#[derive(Debug, Clone)]
pub struct Erc20ApprovalGasSponsoringExtension {
    /// Human-readable description in advertise `info`.
    pub description: String,
    /// Schema version string.
    pub version: String,
}

impl Default for Erc20ApprovalGasSponsoringExtension {
    fn default() -> Self {
        Self::new()
    }
}

impl Erc20ApprovalGasSponsoringExtension {
    /// Official default description and version `"1"`.
    #[must_use]
    pub fn new() -> Self {
        Self {
            description:
                "The facilitator accepts a raw signed approval transaction and will sponsor the gas fees."
                    .into(),
            version: ERC20_APPROVAL_GAS_SPONSORING_VERSION.into(),
        }
    }
}

impl Extension for Erc20ApprovalGasSponsoringExtension {
    fn id(&self) -> &'static str {
        ERC20_APPROVAL_GAS_SPONSORING_KEY
    }

    fn advertise(&self, _ctx: &AdvertiseContext<'_>) -> Option<ExtensionEntry> {
        Some(ExtensionEntry::with_schema(
            json!({
                "description": self.description,
                "version": self.version,
            }),
            client_info_schema(),
        ))
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn advertise_key_and_version() {
        let ext = Erc20ApprovalGasSponsoringExtension::new();
        assert_eq!(ext.id(), "erc20ApprovalGasSponsoring");
        let Some(entry) = ext.advertise(&AdvertiseContext::new(None)) else {
            panic!("erc20 advertise must emit an entry");
        };
        let v = entry.to_value();
        assert_eq!(v["info"]["version"], "1");
        assert!(
            v.get("schema").is_some(),
            "client schema must be advertised"
        );
    }
}