Repository navigation
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Unresolved critical flaws can authorize transfers beyond the spend cap, exhaust client memory, and corrupt downloaded binary resources.
7 open issues
Reject unexpected nested calls in payment authorization trees · New Bound server-provided decimals before formatting · New Preserve resource bytes in text-mode output · New Verify the RPC network before building checkout authorization · New Resolve authorization signer from the requested signing method · New Continue scanning network matches for a supported fee-sponsored option · New Add CLI integration tests for checkout authorization and replay · New
What changed in this PR
Adds stellar checkout <URL> to fetch x402-protected resources using existing Stellar identities and network configuration. Payments use authorization-signed SEP-41 transfers that a fee-sponsoring facilitator submits.
Changes:
- Adds challenge selection, spend-cap enforcement, payment-proof construction, and HTTP replay.
- Supports build-only proofs, JSON receipts, and payment failure diagnostics.
- Registers the command, documents its options, and adds unit tests.
| File | Description |
|---|---|
FULL_HELP_DOCS.md |
Documents checkout usage and options. |
cmd/soroban-cli/src/env_vars.rs |
Registers the checkout spend-cap environment variable. |
cmd/soroban-cli/src/commands/pay/payment.rs |
Builds payment proofs and diagnoses transfer failures. |
cmd/soroban-cli/src/commands/pay/mod.rs |
Coordinates checkout, proof output, and receipts. |
cmd/soroban-cli/src/commands/pay/http.rs |
Fetches resources and replays requests with payment proofs. |
cmd/soroban-cli/src/commands/pay/challenge.rs |
Parses challenges, selects payment options, and decodes settlements. |
cmd/soroban-cli/src/commands/pay/cap.rs |
Parses and enforces display-unit spending limits. |
cmd/soroban-cli/src/commands/mod.rs |
Registers and dispatches the checkout command. |
cmd/soroban-cli/src/commands/contract/invoke.rs |
Adds authorization-only transaction construction for payment proofs. |
cmd/soroban-cli/src/cli.rs |
Integrates checkout with structured JSON error output. |
Review effort: Balanced
|
@leighmcculloch @marcelosalloum can i get some 👀 on this? |
marcelosalloum
left a comment
There was a problem hiding this comment.
Great job working on this 👏.
I left some comments below, happy to review again once they've been addressed.
| if self.sign_with_ledger { | ||
| return Ok(Some(Signer { | ||
| kind: SignerKind::Ledger(LedgerEntry { | ||
| hd_path: self.hd_path.unwrap_or_default(), | ||
| public_key: None, | ||
| }), | ||
| print: print.clone(), | ||
| })); |
There was a problem hiding this comment.
stellar checkout --sign-with-ledger panics before it uses the device. This branch creates the Ledger entry with public_key: None. Then sign_soroban_authorizations calls get_public_key() on each signer. For Ledger, that function calls .expect() on the public key.
| /// Number of ledgers to add to the current ledger so the authorization signature | ||
| /// stays valid for at least `max_timeout_seconds`. | ||
| fn expiry_ledgers(max_timeout_seconds: u64) -> u32 { | ||
| // Round up so a short timeout still yields at least one ledger of validity. | ||
| let ledgers = max_timeout_seconds | ||
| .max(1) | ||
| .div_ceil(ESTIMATED_LEDGER_CLOSE_SECONDS) | ||
| .max(1); | ||
| u32::try_from(ledgers).unwrap_or(u32::MAX) | ||
| } |
There was a problem hiding this comment.
The server sets maxTimeoutSeconds, and the CLI does not set a maximum for it. If the value is very large, the auth entry expires at ledger u32::MAX. Also, with_time_bounds sets the transaction max_time to u64::MAX. Thus, a person can send the signed transfer at any time in the future. The facilitator compares the expiry only with the same server value, so the client must set the limit.
| pub async fn get(url: &str, payment_signature: Option<&str>) -> Result<Response, Error> { | ||
| let client = reqwest::Client::builder().build().map_err(Error::Client)?; | ||
| let mut request = client.get(url); | ||
| if let Some(signature) = payment_signature { | ||
| request = request.header(PAYMENT_SIGNATURE_HEADER, signature); | ||
| } |
There was a problem hiding this comment.
The client follows redirects with the default request policy. On a redirect to a different host, this policy removes only the standard credential headers, for example Authorization and Cookie. It keeps PAYMENT-SIGNATURE. Thus, a redirect on the paid request sends the signed payment to a different host.
| pub struct Settlement { | ||
| #[serde(default)] | ||
| pub transaction: Option<String>, | ||
| #[serde(default)] | ||
| pub network: Option<String>, | ||
| #[serde(rename = "errorReason", default)] | ||
| pub error_reason: Option<String>, | ||
| #[serde(rename = "errorMessage", default)] | ||
| pub error_message: Option<String>, | ||
| } |
There was a problem hiding this comment.
The x402 SettlementResponse has a success field, but Settlement does not read it. If a 2xx response contains success: false in PAYMENT-RESPONSE, the CLI shows "✅ Payment settled" and gives a receipt.
| pub fn amount_raw(&self) -> Result<i128, Error> { | ||
| let raw = self | ||
| .amount | ||
| .as_deref() | ||
| .or(self.max_amount_required.as_deref()) | ||
| .ok_or(Error::MissingAmount)?; | ||
| raw.parse::<i128>() | ||
| .map_err(|_| Error::InvalidAmount(raw.to_string())) |
There was a problem hiding this comment.
The client should reject negative amounts
| let client = reqwest::Client::builder().build().map_err(Error::Client)?; | ||
| let mut request = client.get(url); | ||
| if let Some(signature) = payment_signature { | ||
| request = request.header(PAYMENT_SIGNATURE_HEADER, signature); | ||
| } | ||
| let response = request.send().await.map_err(|source| Error::Request { | ||
| url: url.to_string(), | ||
| source, | ||
| })?; | ||
| let status = response.status().as_u16(); | ||
| let headers = response.headers().clone(); | ||
| let body = response | ||
| .bytes() | ||
| .await | ||
| .map_err(|source| Error::Request { | ||
| url: url.to_string(), | ||
| source, | ||
| })? | ||
| .to_vec(); |
There was a problem hiding this comment.
The client has no request timeout. Also, it reads all of the body into memory with no size limit. A slow or malicious server can stop the CLI or use all of the memory. Plz add a timeout and a content length cap
| /// Maximum amount to pay, in the asset's display units (e.g. `1` = 1.0 USDC, | ||
| /// roughly $1). Aborts before signing if the challenge asks for more. Set to | ||
| /// `none` to disable the cap. |
There was a problem hiding this comment.
Hm, we should consider fetching the decimals from the asset contract if we're not already doing that.
The helper text could mention what 1.0 USDC would look like in a contract invocation (10000000 stroops)
There was a problem hiding this comment.
What if this conversion was an option and we still allowed people to rely on stroops (raw amounts)?
| #[error("the server's 402 response carried no payment declaration")] | ||
| MissingChallenge, |
There was a problem hiding this comment.
I know this is only for x402, but I'd like to mention MPP would have WWW-Authenticate: Payment … method="stellar" rather than PAYMENT-REQUIRED. My point is that this error could mention either that x402 is not supported or that the 402 response is not a protocol supported by the CLI client.


What
Adds
stellar checkout <URL>, an x402 client. When the server responds with a 402, it builds and auth-signs a SEP-41transferand retries the request with the payment proof. The facilitator then submits it and pays the fees. Options:--max-amountsets a spend cap (default1),--build-onlyprints the proof without paying, and--output jsonreturns a receipt. Errors give the facilitator's reason, or name the account with a missing trustline or a low balance.Why
It lets Stellar users pay for x402-protected resources from the CLI with their existing identities and networks.
Close #2621
Known limitations
Only the
exactscheme with fee-sponsoring facilitators is supported, and muxed payers aren't. Tested end to end against stellar/x402-stellar on testnet, which needs@x402/*≥ 2.29.