Skip to content

Commit 62bd9c2

Browse files
rotilhorotilho
committed
Add scheme_exact_atto.md
1 parent d52ef99 commit 62bd9c2

File tree

1 file changed

+269
-0
lines changed

1 file changed

+269
-0
lines changed

‎specs/schemes/exact/scheme_exact_atto.md‎

Lines changed: 269 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,269 @@
1+
# Scheme: `exact` on `Atto`
2+
3+
## Summary
4+
5+
The `exact` scheme on Atto uses a single native Atto `SEND` transaction to transfer a specific amount of the Atto asset from the payer to the resource server.
6+
7+
Atto is a feeless, account‑chain–style network optimized for high‑frequency micropayments. Instead of gas fees, senders perform a small proof‑of‑work (PoW) locally to prevent spam. This makes Atto a good fit for machine‑to‑machine use cases (AI agents, IoT devices) that need fast, cheap, and frequent payments.
8+
9+
This document describes how to:
10+
11+
* Express payment requirements for the `exact` scheme on Atto using the standard x402 `PaymentRequirements` structure.
12+
* Encode a signed Atto `SEND` transaction in an x402 `PaymentPayload`.
13+
* Verify and settle the payment on the Atto network.
14+
15+
16+
## PaymentRequirements
17+
18+
The `exact` scheme on Atto uses the **standard** x402 `PaymentRequirements` shape defined in the core specification. No additional top‑level fields are introduced; any scheme‑specific metadata must go inside the `extra` object.
19+
20+
For Atto, a `paymentRequirements` object inside the `accepts` array has the following semantics:
21+
22+
* `scheme` — MUST be `"exact"`.
23+
* `network` — Atto network identifier, for example:
24+
25+
* `"atto-live"` for mainnet.
26+
* `"atto-beta"` for testnet.
27+
* `"atto-dev"` for devnet.
28+
* `maxAmountRequired` — String representation of the required amount in **raw Atto units** (the smallest unit).
29+
* `asset` — Identifies the asset being paid. It SHOULD be the literal string `"atto"`.
30+
* `payTo` — Atto destination address for the payment. For example:
31+
* `"atto://abzekkyvhsos74rfeibubjifbjdzy3bi7habx5o3kt4ot2vcl5uhb2rcrn7hu"`.
32+
* `resource` — URL or identifier of the protected resource.
33+
* `description` — Human‑readable description of what is being purchased.
34+
* `mimeType` — MIME type of the resource response (e.g. `"application/json"`).
35+
* `outputSchema` (optional) — JSON schema describing the response body.
36+
* `maxTimeoutSeconds` — Maximum time the resource server is willing to wait for verification/settlement before considering the payment expired.
37+
38+
### Example PaymentRequirements Response
39+
40+
```json
41+
{
42+
"x402Version": 1,
43+
"accepts": [
44+
{
45+
"scheme": "exact",
46+
"network": "atto-live",
47+
"maxAmountRequired": "500000000",
48+
"asset": "atto",
49+
"payTo": "atto://abzekkyvhsos74rfeibubjifbjdzy3bi7habx5o3kt4ot2vcl5uhb2rcrn7hu",
50+
"resource": "https://api.example.com/premium-article",
51+
"description": "Access Premium Article (0.5 Atto)",
52+
"mimeType": "application/json",
53+
"outputSchema": null,
54+
"maxTimeoutSeconds": 60
55+
}
56+
]
57+
}
58+
```
59+
60+
In this example, the client must pay **exactly** `500000000` raw units of Atto to the `payTo` address on the `atto-live` network to access the resource.
61+
62+
## `X-PAYMENT` header payload
63+
64+
The `X-PAYMENT` header is a Base64‑encoded JSON `PaymentPayload` as defined in the x402 spec. For Atto, the `payload` field wraps a serialized Atto `SEND` transaction.
65+
66+
At a high level:
67+
68+
1. The client reads the `paymentRequirements` and determines the amount:
69+
70+
* `requiredAmount = paymentRequirements.maxAmountRequired` (as a string; treat as an integer in raw units).
71+
2. The client constructs and signs an Atto `SEND` transaction that:
72+
73+
* Sends `requiredAmount` to `paymentRequirements.payTo`.
74+
* Uses the correct Atto network and protocol version.
75+
3. The client serializes the transaction to a 206‑byte binary form and encodes it as Base64.
76+
4. The client builds the x402 `PaymentPayload` JSON and Base64‑encodes that JSON to form the `X-PAYMENT` header.
77+
78+
### 1. Atto transaction payload
79+
80+
The inner Atto payment is a standard `SEND` transaction serialized into a 206‑byte structure:
81+
82+
| Segment | Field | Size (bytes) | Description |
83+
| ------- | --------------- | ------------ | ------------------------------------------------ |
84+
| Block | Type | 1 | Transaction type (`2` for `SEND`). |
85+
| | Network | 1 | Atto network identifier. |
86+
| | Version | 2 | Atto protocol version. |
87+
| | Algorithm | 1 | Signature algorithm identifier (e.g. `V1`). |
88+
| | Public Key | 32 | Sender’s public key. |
89+
| | Height | 8 | Account height / sequence number. |
90+
| | Balance | 8 | New balance after the transfer. |
91+
| | Timestamp | 8 | Transaction timestamp. |
92+
| | Previous | 32 | Hash of the previous block in the account chain. |
93+
| | Receiver Algo | 1 | Receiver’s algorithm identifier. |
94+
| | Receiver PubKey | 32 | Receiver’s public key (derived from `payTo`). |
95+
| | Amount | 8 | Amount being sent in raw Atto units. |
96+
| Auth | Signature | 64 | Ed25519 signature over the block contents. |
97+
| PoW | Work | 8 | Proof‑of‑work nonce. |
98+
| Total | | **206** | Full serialized Atto `SEND` transaction. |
99+
100+
The client serializes this structure and encodes it as a Base64 string:
101+
102+
```text
103+
base64Transaction = base64(206-byte-atto-send-transaction)
104+
```
105+
106+
### 2. PaymentPayload JSON
107+
108+
The decoded `X-PAYMENT` header MUST be a JSON object with this shape:
109+
110+
```json
111+
{
112+
"x402Version": 1,
113+
"scheme": "exact",
114+
"network": "atto-live",
115+
"payload": {
116+
"transaction": "<Base64-encoded 206-byte Atto SEND transaction>"
117+
}
118+
}
119+
```
120+
121+
* `scheme` must be `"exact"`.
122+
* `network` must match the selected `paymentRequirements.network`.
123+
* `payload.transaction` is the Base64 string produced in the previous step.
124+
125+
### 3. HTTP header encoding
126+
127+
On the wire, the client sends:
128+
129+
```http
130+
X-PAYMENT: <base64-encoded-PaymentPayload-JSON>
131+
```
132+
133+
Where `<base64-encoded-PaymentPayload-JSON>` is the Base64 encoding of the JSON object above. Header name is case‑insensitive, but `X-PAYMENT` is RECOMMENDED.
134+
135+
136+
## Verification
137+
138+
A facilitator or resource server verifying an Atto `exact` payment SHOULD perform at least the following steps:
139+
140+
1. **Decode `X-PAYMENT` header**
141+
142+
* Base64‑decode the header value to obtain the `PaymentPayload` JSON.
143+
* Validate:
144+
145+
* `x402Version === 1`
146+
* `scheme === "exact"`
147+
* `network` matches the `paymentRequirements.network`.
148+
149+
2. **Validate PaymentRequirements**
150+
151+
* Ensure `paymentRequirements.scheme === "exact"`.
152+
* Ensure `paymentRequirements.network` is an Atto network the verifier supports (e.g. `"atto-live"`).
153+
* Confirm `maxAmountRequired`, `asset`, and `payTo` are present and well‑formed.
154+
155+
3. **Decode Atto transaction**
156+
157+
* Read `payload.transaction` from the `PaymentPayload`.
158+
* Base64‑decode it to a 206‑byte buffer.
159+
* Parse fields according to the Atto `SEND` layout above and reject if:
160+
161+
* Length ≠ 206 bytes.
162+
* The `Type` field is not `SEND`.
163+
* Network / version fields are not recognized.
164+
165+
4. **Signature verification**
166+
167+
* Recompute the block hash per Atto’s rules.
168+
* Verify the Ed25519 signature using the `Public Key` field.
169+
* Reject if signature verification fails.
170+
171+
5. **Proof‑of‑Work verification**
172+
173+
* Derive the PoW target/difficulty from network configuration.
174+
* Verify the `Work` field meets the required difficulty.
175+
* Reject if PoW is insufficient.
176+
177+
6. **Replay protection**
178+
179+
* Check that:
180+
181+
* `Previous` has not already been used for a confirmed `SEND`.
182+
* `Height` is strictly greater than the last confirmed height for the account.
183+
* `Timestamp` is within an acceptable window (to prevent very old or far‑future transactions).
184+
* These checks MUST take place, node transaction publishing is idempotent!
185+
186+
7. **Recipient & asset checks**
187+
188+
* Derive the expected receiver public key from `paymentRequirements.payTo` using Atto address rules.
189+
* Confirm the transaction’s `Receiver PubKey` matches this derived key.
190+
* Confirm `asset` in `paymentRequirements` is `"atto"` (or another Atto asset the verifier explicitly supports).
191+
192+
8. **Amount validation**
193+
194+
* Interpret the transaction’s `Amount` field as an unsigned long in raw Atto units (`txAmount`).
195+
* Interpret `paymentRequirements.maxAmountRequired` as `requiredAmount`.
196+
* Check that `txAmount == requiredAmount`.
197+
198+
If all checks pass, the payment is valid for the selected `paymentRequirements`.
199+
200+
## Settlement
201+
202+
Once a payment has been verified:
203+
204+
1. **Broadcast**
205+
206+
* The facilitator or resource server submits the validated `SEND` transaction to an Atto node.
207+
208+
2. **Consensus**
209+
210+
* The transaction is incorporated into Atto’s consensus (e.g., via Open Representative Voting).
211+
212+
3. **Finality**
213+
214+
* After confirmation, the `SEND` is final and cannot be reversed. Atto is designed for sub‑second deterministic finality.
215+
216+
4. **Receiving wallet handling (optional)**
217+
218+
* Atto requires a corresponding `RECEIVE` block to update the receiver’s balance.
219+
* From the perspective of x402 and this scheme, the payment is considered **settled** once the `SEND` is confirmed on‑chain; a later `RECEIVE` block is an internal wallet detail.
220+
221+
## Appendix: Example
222+
223+
Below is a complete example showing a client paying for a JSON API response with Atto using the `exact` scheme.
224+
225+
### Example PaymentRequirementsResponse
226+
227+
```json
228+
{
229+
"x402Version": 1,
230+
"error": "X-PAYMENT header is required",
231+
"accepts": [
232+
{
233+
"scheme": "exact",
234+
"network": "atto-live",
235+
"maxAmountRequired": "500000000",
236+
"asset": "atto",
237+
"payTo": "atto://aabaeaqcaibaeaqcaibaeaqcaibaeaqcaibaeaqcaibaeaqcaibaevjhdj47s",
238+
"resource": "https://api.example.com/premium-article",
239+
"description": "Access Premium Article (0.5 Atto)",
240+
"mimeType": "application/json",
241+
"outputSchema": null,
242+
"maxTimeoutSeconds": 60,
243+
"extra": null
244+
}
245+
]
246+
}
247+
```
248+
249+
### Example PaymentPayload (decoded `X-PAYMENT`)
250+
251+
```json
252+
{
253+
"x402Version": 1,
254+
"scheme": "exact",
255+
"network": "atto-live",
256+
"payload": {
257+
"transaction": "BASE64_ENCODED_ATTO_SEND_TX=="
258+
}
259+
}
260+
```
261+
262+
The client sends:
263+
264+
```http
265+
X-PAYMENT: eyJ4NDAyVmVyc2lvbiI6MSwic2NoZW1lIjoiZXhhY3QiLCJuZXR3b3JrIjoiYXR0by1saXZlIiwicGF5bG9hZCI6eyJ0cmFuc2FjdGlvbiI6IkJBU0U2NF9FTkNPREVERF9BVFRPX1NFTkRfVFhfLi4uPSJ9fQ==
266+
```
267+
268+
Where the header value is the Base64 encoding of the `PaymentPayload` JSON above.
269+

0 commit comments

Comments
 (0)