Skip to content

Define canonical JSON encoding for unsigned 64-bit integers #343

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
robwoodgate wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Define canonical JSON encoding for unsigned 64-bit integers #343

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
cad8cad
define UInt64Json, int, u64. Use UInt64Json for JSON amounts
robwoodgate Feb 18, 2026
271f56c
address review comments
robwoodgate Apr 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion 00.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,11 +56,22 @@ These specifications use elliptic curve public key cryptography over the field a

### Types

Values in these specification are one of:
Values in this specification are one of:

- Scalars: integers modulo the curve order `n`
- Curve points: elements of the elliptic curve group (including the identity point at infinity)
- Byte sequences
- `int` / `u64`: unsigned 64-bit integer in the range: `0..2^64-1`.

#### Unsigned 64-bit integers in JSON fields

For JSON fields, `int` / `u64` values may be encoded as a JSON integer number or a base-10 decimal string.

Implementations **MUST** accept both forms.
Copy link
Copy Markdown
Contributor Author

@robwoodgate robwoodgate Feb 21, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we want to encourage a single standard (decimal string) over time, we could tweak:

Suggested change
Implementations **MUST** accept both forms.
Implementations **MUST** accept both forms, and **SHOULD** encode values as decimal strings.

We already consistently use string amounts in the /v1/keys api, so this would be a continuation of that precedent.


Values greater than `9007199254740991 (2^53-1)` **MUST** be represented as decimal strings.

This preserves integer precision in environments where JSON numbers use IEEE-754.

### Byte Operations And Encodings

Expand Down
2 changes: 1 addition & 1 deletion 01.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ Response `GetKeysResponse` of `Bob`:
"input_fee_ppk": <int|null>,
"final_expiry": <unix_timestamp_int|null>
"keys": {
<amount_int>: <public_key_str>,
<amount_str>: <public_key_str>,
...
}
}
Expand Down
2 changes: 1 addition & 1 deletion 18.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ A Payment Request is defined as follows
Here, the fields are

- `i`: Payment id to be included in the payment payload
- `a`: The amount of the requested payment
- `a`: The amount of the requested payment as an [unsigned int][00]
- `u`: The unit of the requested payment (MUST be set if `a` is set)
- `s`: Whether the payment request is for single use
- `m`: A set of mints from which the payment is requested
Expand Down
3 changes: 2 additions & 1 deletion 24.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ HTTP servers may respond with the HTTP status code 402 with a `X-Cashu` header c
}
```

- `a`: The amount required in the specified unit
- `a`: The amount required in the specified unit as an [unsigned int][00]
- `u`: The currency unit (e.g., "sat", "usd", "api")
- `m`: Array of mint URLs that the server accepts tokens from
- `nut10`: The required [NUT-10][10] locking condition
Expand All @@ -40,6 +40,7 @@ The token MUST be from one of the mints listed in the `mints` array, and MUST be

If the server receives tokens from a mint that is not in the `mints` array, an incorrect `unit`, an insufficient amount of tokens, or with insufficient locking conditions, it should respond with a HTTP `400` status code.

[00]: 00.md
[10]: 10.md
[12]: 12.md
[18]: 18.md
Expand Down
Loading