Scheme: exact on Algorand
Summary
The exact scheme on Algorand uses the Algorand Standard Asset (ASA), native assets (no contract required) of the Algorand protocol, to authorize a transfer of a specific amount from the payor to the resource server. The approach results in the facilitator having no ability to direct funds anywhere but the address specified by the resource server in paymentRequirements.
Sequence of operations
sequenceDiagram
participant C as Client
participant R as Resource Server
participant F as Facilitator
participant A as Algorand
C->>R: Request Resource
R-->>C: 402 Payment Required + paymentRequirements
C->>C: Construct paymentGroup of transactions
C->>C: Sign relevant transactions in paymentGroup
C->>R: Resend request with PAYMENT-SIGNATURE header
R->>F: Verify paymentGroup
alt valid
F-->>F: Check/Sign feePayer transaction
F-->>A: Simulate paymentGroup
A-->>F: Simulation result
alt simulation success
F-->>R: Payment verified
R->>F: Request settlement
F-->>A: Submit paymentGroup
A-->>F: Transaction result
alt success - Instant Finality
F-->>R: Settlement successful
R-->>C: 200 OK + Resource
else
F-->>R: Settlement failed
R-->>C: 402 Payment Required (invalid payment)
end
else simulation fail
F-->>R: Payment invalid
R-->>C: 402 Payment Required (invalid payment)
end
else invalid
R-->>C: 402 Payment Required (invalid payment)
end
paymentRequirements for Payment Required Response
In the exact scheme on Algorand, the paymentRequirements record MAY include a feePayer field inside the extra element. This informs the client they MAY construct a transaction that includes a 0 Algo payment transaction, from the feePayer, with a fee value that’s enough to cover the cost of their transaction(s). This transaction would be included in the same atomic group as the expected asset transfer transaction, and will be signed by the Facilitator after verifying the transaction group and before settling to the network.
Additionally the paymentRequirements.asset field MUST be a string representing an ASA ID (64-bit unsigned integer) instead of an ERC20 contract address. This MUST be validated by the resource server to ensure the asset field is valid when using the Algorand scheme.
paymentRequirements.extra specification:
{
// Optional Algorand address that will pay the transaction fees.
feePayer?: string;
}
Full paymentRequirements Example:
{
"scheme": "exact",
"network": "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k",
"amount": "5000000",
"payTo": "RESOURCESERVERADDRESSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALTSRPAE",
"maxTimeoutSeconds": 60,
"asset": "31566704",
"extra": {
"feePayer": "FACILITATORADDRESSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALQCXBZE"
}
}
PAYMENT-SIGNATURE Header Payload
The payload field of the PAYMENT-SIGNATURE header MUST contain paymentGroup as a field. It represents an atomic group of transactions as an array. Transaction groups are natively supported by the Algorand protocol (no contract required), enabling the execution of several transactions (even with different authorizers) processed atomically (no partial execution is allowed, either all the transactions in the group succeed or the entire group is rejected).
A group can contain several different types of transactions, such as pay (transfer of ALGO native protocol asset) and axfer (transfer of generic ASA), and others (for further details on supported transaction types, refer to the Algorand transactions documentation.
As part of the payload there MUST also be a paymentIndex field which identifies the transaction in the group that will pay the resource server. The group may perform several operations to facilitate the payment, such as swaps or asset transfers, but only one transaction in the group will actually transfer the funds to the resource server.
In a single standalone transaction, the
paymentIndexMUST be set to 0.
Multiple signers can be in the group, and fees can be pooled together or assigned to a specific signer, meaning they can be delegated to a specific account to pay the fees for the group. A group can include a maximum of:
- 16 top-level transactions, authorized either with a single signature (
Ed25519), ak-of-nthreshold multi-signature, or a logic signature; - 256 inner transactions, authorized by an application (smart contract).
Example of a USDC asset transfer with an abstracted fee (i.e paid by the facilitator):
{
"paymentIndex": 1, // 0th index of the transaction in the group that will pay the resource server
"paymentGroup": [
"gaN0eG6Jo2ZlZc0H0KJmds4DLgNro2dlbqxtYWlubmV0LXYxLjCiZ2jEIMBhxNj8Hb3e0tdgS+RWjj9tBBmHrDe95LYgtas5JIrfo2dycMQgfy1Szr+lgvgTJsviMY2KnHSsXqyfCJ1UOCE+2Tf3vS+ibHbOAy4HU6NyY3bEICgEhaJgm6IBjiSUgAAAAAAAAAAAAAAAAAAAAAAAAAAAo3NuZMQgKASFomCbogGOJJSAAAAAAAAAAAAAAAAAAAAAAAAAAACkdHlwZaNwYXk=",
"gqNzaWfEQP3J1DI6GLSfK0nLZftvSyVMJuFOE48xPlnZpNdEJWbGbcxsD5aASwza4TjbwhgEF0dXOv8E3W/f22vkEzfFywWjdHhuiaRhYW10zgBMS0CkYXJjdsQgiSTqRESRI1JEAxxJKQAAAAAAAAAAAAAAAAAAAAAAAACiZnbOAy4Da6JnaMQgwGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit+jZ3JwxCB/LVLOv6WC+BMmy+IxjYqcdKxerJ8InVQ4IT7ZN/e9L6Jsds4DLgdTo3NuZMQgEtBGzAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACkdHlwZaVheGZlcqR4YWlkzgHhq3A="
]
}
Full PAYMENT-SIGNATURE header example:
{
"x402Version": 2,
"scheme": "exact",
"network": "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k",
"resource": {
"url": "https://example.net/signup",
"description": "$5 registration payment",
"mimeType": "text/html"
},
"accepted": {
"scheme": "exact",
"network": "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k",
"amount": "5000000",
"payTo": "RESOURCESERVERADDRESSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALTSRPAE",
"maxTimeoutSeconds": 60,
"asset": "31566704",
"extra": {
"feePayer": "FACILITATORADDRESSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALQCXBZE"
}
},
"extensions": {},
"outputSchema": null,
"payload": {
"paymentIndex": 1,
"paymentGroup": [
"gaN0eG6Jo2ZlZc0H0KJmds4DLgNro2dlbqxtYWlubmV0LXYxLjCiZ2jEIMBhxNj8Hb3e0tdgS+RWjj9tBBmHrDe95LYgtas5JIrfo2dycMQgfy1Szr+lgvgTJsviMY2KnHSsXqyfCJ1UOCE+2Tf3vS+ibHbOAy4HU6NyY3bEICgEhaJgm6IBjiSUgAAAAAAAAAAAAAAAAAAAAAAAAAAAo3NuZMQgKASFomCbogGOJJSAAAAAAAAAAAAAAAAAAAAAAAAAAACkdHlwZaNwYXk=",
"gqNzaWfEQP3J1DI6GLSfK0nLZftvSyVMJuFOE48xPlnZpNdEJWbGbcxsD5aASwza4TjbwhgEF0dXOv8E3W/f22vkEzfFywWjdHhuiaRhYW10zgBMS0CkYXJjdsQgiSTqRESRI1JEAxxJKQAAAAAAAAAAAAAAAAAAAAAAAACiZnbOAy4Da6JnaMQgwGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit+jZ3JwxCB/LVLOv6WC+BMmy+IxjYqcdKxerJ8InVQ4IT7ZN/e9L6Jsds4DLgdTo3NuZMQgEtBGzAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAACkdHlwZaVheGZlcqR4YWlkzgHhq3A="
]
}
}
PAYMENT-RESPONSE Header
Upon a successful settlement, the PAYMENT-RESPONSE MUST return the transaction ID of the paymentGroup[paymentIndex] transaction. This identifies the specific asset transfer transaction to the payTo address for the amount, and can be used to identify the transaction on the network.
Should the settlement fail, the transaction ID SHOULD be returned, but since failed transactions are not committed to the network, it might not be visible on the chain.
Full PAYMENT-RESPONSE header example:
{
"success": true,
"errorReason": null,
"payer": "<payer>",
"transaction": "NTRZR6HGMMZGYMJKUNVNLKLA427ACAVIPFNC6JHA5XNBQQHW7MWA",
"network": "algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k"
}
Verification
Steps to verify a payment for the exact scheme on Algorand:
- Validate
x402Versionis a supported version (currently2). - Validate
schemeis"exact"in both thePAYMENT-SIGNATUREpayloadacceptedfield and thepaymentRequirements. - Validate
networkmatches between thePAYMENT-SIGNATUREpayloadacceptedfield and thepaymentRequirements. - Check the
paymentGroupcontains 16 or fewer elements. - Decode all transactions from the
paymentGroup. - Locate the
paymentGroup[paymentIndex]transaction from thePayment Payload.- Check the
aamt(asset amount) matchesamountfrom thePayment Requirements. - Check the
arcv(asset receiver) matchespayTofrom thePayment Requirements. - Check the
xaid(asset ID) matchesassetfrom thePayment Requirements.
- Check the
- Locate all transactions where
snd(sender) is theFacilitators Algorand address.- Check the
type(transaction type) ispay. - Check the following fields are omitted:
close,rekey,amt. - Check the
fee(Fee) is a reasonable amount. - Sign the transaction.
- Check the
- Evaluate the payment group against an Algorand node’s
simulateendpoint to ensure the transactions would succeed.
Settlement
Once the group is validated by the resource server, settlement can occur by the facilitator submitting the verified transaction group to the Algorand network through the v2/transactions endpoint against any valid Algorand node.
In Algorand there are no consensus forks and so it achieves instant finality the moment a transaction is included in a block. So as soon as the transaction is included in a block, the payment is considered settled and the facilitator can inform the resource server of the successful payment and proceed with the resource delivery.
Network Identifiers (CAIP-2)
Algorand network values MUST use CAIP-2 identifiers in the algorand namespace. The reference is the URL-safe base64 encoding of the genesis hash, truncated to the first 32 characters as defined by the Algorand CAIP-2 namespace profile. Full genesis hashes are used only in onchain transaction gh fields, never in network values.
| Network | CAIP-2 |
|---|---|
| Mainnet | algorand:wGHE2Pwdvd7S12BL5FaOP20EGYesN73k |
| Testnet | algorand:SGO1GKSzyE7IEPItTxCByw9x8FmnrCDe |
See the Algorand CAIP-2 namespace profile for the encoding rules.
Additional Considerations
Assets
In order for the resource server to receive payment on a particular Asset, it MUST be opted-in to that asset. In Algorand, accounts explicitly enable receiving a particular asset, otherwise an asset transfer to that account will be rejected. So as part of the resource server’s setup, it SHOULD ensure it has opted-in to the asset ID specified in the paymentRequirements.asset.
Multiple Payments
The facilitator may want to account for multiple payments and feePayer transactions in a single group. If the client knows what they’re paying for and constructs multiple payments in one group, there could be up to 16 payments to the resource server, or 8 gasless payments.
Signature Scheme
Each top-level transaction in the paymentGroup MUST be signed individually by each of the owners of the sender addresses in the group.
In Algorand, signatures of top-level transactions are based either on:
- A
Ed25519single signature scheme (sig); - A
k-of-nthreshold multi-signature (msig); - A Logic Signature, verified by the Algorand Virtual Machine (
lsig);
Algorand Addresses and Public Key relationship
In Algorand, addresses are 58-character base32-encoded representations of either:
- SHA512_256 of the Logic Signatures program bytecode +
Programas a prefix. - Public keys, with a sha512_256 checksum (last 4 bytes) appended as a suffix. This encoding ensures that addresses can be derived directly from public keys without requiring a pre-existing signature for operations like
ecRecoverto verify signatures.
Example of encoding Algorand addresses:
encodeAddress(publicKey: Buffer): string {
const keyHash: string = sha512_256.create().update(publicKey).hex()
// last 4 bytes of the hash
const checksum: string = keyHash.slice(-8)
return base32.encode(Encoder.ConcatArrays(publicKey, Buffer.from(checksum, "hex"))).slice(0, 58)
}
Encoding
Algorand uses msgpack to encode the transactions. Each element in the paymentGroup array can be base64-decoded, then msgpack-decoded, to reveal the transaction contents. Or using goal you can do the following:
% cat payload.json | jq -r '.paymentGroup[]' | base64 -d | goal clerk inspect -
-[0]
{
"txn": {
"fee": 2000,
"fv": 53347179,
"gen": "mainnet-v1.0",
"gh": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
"grp": "fy1Szr+lgvgTJsviMY2KnHSsXqyfCJ1UOCE+2Tf3vS8=",
"lv": 53348179,
"rcv": "FACILITATORADDRESSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALQCXBZE",
"snd": "FACILITATORADDRESSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALQCXBZE",
"type": "pay"
}
}
-[1]
{
"sig": "/cnUMjoYtJ8rSctl+29LJUwm4U4TjzE+Wdmk10QlZsZtzGwPloBLDNrhONvCGAQXR1c6/wTdb9/ba+QTN8XLBQ==",
"txn": {
"aamt": 5000000,
"arcv": "RESOURCESERVERADDRESSAAAAAAAAAAAAAAAAAAAAAAAAAAAAAALTSRPAE",
"fv": 53347179,
"gh": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
"grp": "fy1Szr+lgvgTJsviMY2KnHSsXqyfCJ1UOCE+2Tf3vS8=",
"lv": 53348179,
"snd": "CLIENTAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHFUPIRI",
"type": "axfer",
"xaid": 31566704
}
}
Appendix
Gasless Transactions/Sponsored Fees
Facilitators who offer “gasless” transactions, may refuse to sign their feePayer transaction, if they consider it’s been constructed maliciously. These malicious checks may be off-loaded to a logic signature, where the facilitator instead provides their signature of the TxID as an argument.