You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Receipt documentation differs from verification code #264
I found two differences between the ACK-Pay receipt documentation and the verification code at 3db94d6. I'm mapping ACK's credentials for the Agent Governance Vocabulary and want to make sure I understand what a verified receipt proves.
1. Proof format
docs/ack-pay/receipt-verification.mdx shows an Ed25519Signature2020 proof with a proofValue.
But verifyProof in packages/vc/src/verification/verify-proof.ts accepts only JwtProof2020 and throws UnsupportedProofTypeError for other proof types.
Should the example use a JWT proof, or is support for the documented proof type intended?
2. Payment amount
The same page shows amount, currency, decimals, recipient and a settlement timestamp in credentialSubject.metadata. It tells the server to check those fields, but also describes metadata as non-normative.
The current verifyPaymentReceipt checks paymentOptionId and the signed request token. It does not check those metadata fields.
If the settled amount differs from the offered amount, what does a successfully verified receipt establish, which payment option the client selected or how much actually settled?
If these behaviors are intentional, could the docs clarify them? I can prepare a documentation PR once I know the intended behavior. A pointer to the v2 redesign would also help if it replaces these sections.
AI use. Claude helped compare the files and draft the findings, and ChatGPT helped revise the wording. I checked the reported differences against commit 3db94d6.
Independent confirmation of both points, read from the source at 3db94d6 (still the head of main today). Disclosure: I maintain INAM Protocol, another receipt format; I am not affiliated with ACK and I only read the two files below, I did not run the package.
1. Proof format: confirmed.verifyProof in packages/vc/src/verification/verify-proof.ts has one case, JwtProof2020, and throws UnsupportedProofTypeError for everything else. The Ed25519Signature2020 / proofValue example in docs/ack-pay/receipt-verification.mdx (lines 50 to 54) would therefore be rejected by the code it documents.
2. Amount: confirmed, and it is wider than the amount. After the credential checks, verifyPaymentReceipt (packages/ack-pay/src/verify-payment-receipt.ts) does two things with the payment itself: it verifies the embedded payment request token, and it checks that credentialSubject.paymentOptionId is the id of one of paymentRequest.paymentOptions. It never reads credentialSubject.metadata. Of the six questions listed under "Verify Payment Details" in the doc, the code answers the first two. These are left to the caller:
recipient matches the server;
amount, currency and decimals are sufficient;
the request id is the one the server issued (the function takes no expected id; it returns paymentRequest so the caller can compare);
recency of issuanceDate and the settlement timestamp. The request token is verified with verifyExpiry: false, so an expired request does not fail here either.
So on your last question, as the code stands: a verified receipt establishes that a trusted issuer signed a receipt naming one option of a validly signed request. It does not establish how much settled, in what currency, or to whom, unless the caller checks metadata that the same page calls non-normative.
That may be the intended split (the library checks signatures and binding, the application checks the money). If so, the doc step would be accurate with one sentence saying which of the six checks verifyPaymentReceipt performs and which are the caller's.
Activity
hheskihoran commentedon Nov 18, 2026
Independent confirmation of both points, read from the source at
3db94d6(still the head ofmaintoday). Disclosure: I maintain INAM Protocol, another receipt format; I am not affiliated with ACK and I only read the two files below, I did not run the package.1. Proof format: confirmed.
verifyProofinpackages/vc/src/verification/verify-proof.tshas one case,JwtProof2020, and throwsUnsupportedProofTypeErrorfor everything else. TheEd25519Signature2020/proofValueexample indocs/ack-pay/receipt-verification.mdx(lines 50 to 54) would therefore be rejected by the code it documents.2. Amount: confirmed, and it is wider than the amount. After the credential checks,
verifyPaymentReceipt(packages/ack-pay/src/verify-payment-receipt.ts) does two things with the payment itself: it verifies the embedded payment request token, and it checks thatcredentialSubject.paymentOptionIdis theidof one ofpaymentRequest.paymentOptions. It never readscredentialSubject.metadata. Of the six questions listed under "Verify Payment Details" in the doc, the code answers the first two. These are left to the caller:recipientmatches the server;amount,currencyanddecimalsare sufficient;idis the one the server issued (the function takes no expected id; it returnspaymentRequestso the caller can compare);issuanceDateand the settlementtimestamp. The request token is verified withverifyExpiry: false, so an expired request does not fail here either.So on your last question, as the code stands: a verified receipt establishes that a trusted issuer signed a receipt naming one option of a validly signed request. It does not establish how much settled, in what currency, or to whom, unless the caller checks metadata that the same page calls non-normative.
That may be the intended split (the library checks signatures and binding, the application checks the money). If so, the doc step would be accurate with one sentence saying which of the six checks
verifyPaymentReceiptperforms and which are the caller's.aeoess commentedon Nov 18, 2026
Thanks for catching the expiry check. I missed that in my original review.
I've opened #267 to correct the documentation, including the proof type and the checks left to the application.