docs(ack-pay): map ACK-Pay concepts to MPP and x402 - #142
Conversation
WalkthroughAdded a non-normative interoperability guide for ACK-Pay, MPP, and x402. The guide defines concept mappings, describes rail-neutral receipt handling, and shows protocol-specific metadata without changing the ChangesACK-Pay interoperability
Estimated code review effort: 1 (Trivial) | ~5 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/ack-pay/interoperability.mdx`:
- Around line 38-45: Update the interoperability receipt example so the
protocol-specific evidence object is nested under credentialSubject.metadata,
while keeping paymentRequestToken and paymentOptionId directly under
credentialSubject. Ensure executionRef and settlementNetwork remain within
evidence at the new metadata path.
- Around line 19-20: Update the interoperability mapping table to distinguish
settlement and receipt roles: map x402’s receipt issuer to the resource server,
settlement actor to the facilitator, and ACK receipt issuer to Receipt Service.
In the receipt example, move evidence under credentialSubject.metadata to match
the documented schema.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro Plus
Run ID: 1a3abb64-cf6c-42da-b616-f6873c84463f
📒 Files selected for processing (1)
docs/ack-pay/interoperability.mdx
| | Payment receipt VC | Receipt | Payment Response / signed receipt extension | | ||
| | Receipt issuer | Server / payment verifier | facilitator / resource server | |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- target documentation files ---'
fd -t f -i 'interoperability|receipt-verification' docs
printf '%s\n' '--- interoperability.mdx ---'
target=$(fd -t f -i 'interoperability' docs | head -n 1)
cat -n "$target" | sed -n '1,110p'
printf '%s\n' '--- receipt-verification.mdx ---'
receipt=$(fd -t f -i 'receipt-verification' docs | head -n 1)
cat -n "$receipt" | sed -n '1,115p'
printf '%s\n' '--- relevant ACK-Pay and x402 terminology ---'
rg -n -i -C 3 'receiptService|SettlementResponse|signed receipt|offer-receipt|payment-response|payment verifier|receipt issuer|facilitator|resource server|credentialSubject|metadata' docsRepository: agentcommercekit/ack
Length of output: 26076
🌐 Web query:
x402 official documentation PAYMENT-RESPONSE SettlementResponse optional signed receipt offer-receipt extension facilitator resource server
💡 Result:
In the x402 protocol, the PAYMENT-RESPONSE header is a standardized HTTP header used by the resource server to communicate the outcome of a payment settlement to the client [1][2]. It contains a Base64-encoded SettlementResponse object [1][3][2]. The SettlementResponse schema includes the following fields: success (boolean), transaction (string; blockchain transaction hash), network (string; CAIP-2 format), errorReason (optional string), payer (optional string), amount (optional string), and extensions (optional object) [3][4]. The optional signed receipt is provided through the "offer-receipt" extension [5][6]. When this extension is active: 1. On 200 OK responses, the server signs a receipt confirming service delivery and payment receipt [5][6]. 2. This receipt is included in the extensions field of the SettlementResponse object, which is then transmitted via the PAYMENT-RESPONSE header [5][6][7]. 3. The receipt includes fields such as resourceUrl, payer, network, issuedAt, and an optional txHash [5][6][7]. A facilitator is an optional service that assists the resource server in verifying payment payloads and settling transactions on the blockchain [8][9]. The resource server may interact with a facilitator server by sending the payment payload and details to the facilitator's /verify or /settle endpoints [8]. The facilitator then performs the requested action (such as broadcasting the transaction) and returns a response, which the resource server uses to finalize the settlement and populate the PAYMENT-RESPONSE header [10][8]. Alternatively, servers may use in-process "self-facilitation" to perform these tasks locally [8][11].
Citations:
- 1: https://docs.x402.org/core-concepts/http-402
- 2: https://github.com/x402-foundation/x402/blob/main/specs/transports-v2/http.md
- 3: https://github.com/x402-foundation/x402/blob/main/specs/x402-specification-v2.md
- 4: https://github.com/coinbase/x402/blob/main/specs/x402-specification-v2.md
- 5: https://docs.x402.org/extensions/offer-receipt
- 6: https://github.com/x402-foundation/x402/blob/main/specs/extensions/extension-offer-and-receipt.md
- 7: https://github.com/coinbase/x402/blob/main/specs/extensions/extension-offer-and-receipt.md
- 8: https://docs.x402.org/core-concepts/facilitator
- 9: https://docs.x402.org/dev-tools/facilitators
- 10: https://eco.com/support/en/articles/14839402-x402-protocol-explained
- 11: https://github.com/x402-foundation/x402/blob/main/examples/typescript/servers/self-facilitation/README.md
🌐 Web query:
site:docs.x402.org/extensions/offer-receipt x402 receipt issuer resource server signed receipt
💡 Result:
The x402 protocol uses a specialized extension to handle signed offers and receipts, providing cryptographic proof of interaction between a resource server and a client [1]. In this workflow, the resource server's role regarding receipts is as follows: 1. Signed Offers (402 Responses): When the resource server returns a 402 Payment Required response, the Offer & Receipt extension signs an offer for each accepted payment scheme [1]. This offer commits to specific payment terms, including the network, amount, payment destination, and a validity timestamp [1]. 2. Signed Receipts (200 Responses): After a client completes the payment, the resource server issues a signed receipt upon returning a 200 OK response [1]. This receipt acts as confirmation of service delivery and includes details such as the resource URL, the payer's address, the network, and an issuance timestamp [1]. These receipts are included in the extensions field of the PAYMENT-RESPONSE header [1]. The extension supports verification via EIP-712 or JWS signatures, allowing clients to programmatically verify that the receipt was issued by the trusted resource server [1]. Implementation involves registering the offer-receipt extension with the x402ResourceServer instance on the backend [1].
Citations:
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- ACK role definitions ---'
for f in $(fd -t f -i 'components-roles|server-initiated-sequence|payment-service' docs); do
printf '\n--- %s ---\n' "$f"
rg -n -C 5 -i 'Receipt Service|receiptService|Payment Service|facilitator|settlement|issuer|verif' "$f"
done
printf '%s\n' '--- all x402 references in documentation ---'
rg -n -C 4 -i 'x402|SettlementResponse|PAYMENT-RESPONSE|offer-receipt|signed receipt' docsRepository: agentcommercekit/ack
Length of output: 28856
Separate receipt, settlement, and verification roles.
PAYMENT-RESPONSEcarries aSettlementResponse; only the optionaloffer-receiptextension adds a signed receipt. Map the x402 receipt issuer to the resource server and the settlement actor to the facilitator. Map the ACK receipt issuer toReceipt Service, not the server or payment verifier.- Move
evidenceundercredentialSubject.metadatain the example to match the documented receipt schema.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/ack-pay/interoperability.mdx` around lines 19 - 20, Update the
interoperability mapping table to distinguish settlement and receipt roles: map
x402’s receipt issuer to the resource server, settlement actor to the
facilitator, and ACK receipt issuer to Receipt Service. In the receipt example,
move evidence under credentialSubject.metadata to match the documented schema.
Source: MCP tools
| "credentialSubject": { | ||
| "paymentRequestToken": "...", | ||
| "paymentOptionId": "...", | ||
| "evidence": { | ||
| "executionRef": "x402:0xabc123...", | ||
| "settlementNetwork": "base" | ||
| } | ||
| } |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Place protocol-specific data under credentialSubject.metadata.
The existing receipt contract defines credentialSubject.metadata as the optional extension point. This example places evidence directly under credentialSubject, so implementations that copy it will use a different field path.
Proposed fix
"credentialSubject": {
"paymentRequestToken": "...",
"paymentOptionId": "...",
- "evidence": {
- "executionRef": "x402:0xabc123...",
- "settlementNetwork": "base"
+ "metadata": {
+ "evidence": {
+ "executionRef": "x402:0xabc123...",
+ "settlementNetwork": "base"
+ }
}
}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "credentialSubject": { | |
| "paymentRequestToken": "...", | |
| "paymentOptionId": "...", | |
| "evidence": { | |
| "executionRef": "x402:0xabc123...", | |
| "settlementNetwork": "base" | |
| } | |
| } | |
| "credentialSubject": { | |
| "paymentRequestToken": "...", | |
| "paymentOptionId": "...", | |
| "metadata": { | |
| "evidence": { | |
| "executionRef": "x402:0xabc123...", | |
| "settlementNetwork": "base" | |
| } | |
| } | |
| } |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/ack-pay/interoperability.mdx` around lines 38 - 45, Update the
interoperability receipt example so the protocol-specific evidence object is
nested under credentialSubject.metadata, while keeping paymentRequestToken and
paymentOptionId directly under credentialSubject. Ensure executionRef and
settlementNetwork remain within evidence at the new metadata path.
1 participant
Closes #90Summary by CodeRabbit