ICRC-3 refinement #199

bogwar · 2025-08-06T18:58:50Z

Proposed change to ICRC-3 based on this proposal

Copilot

Pull Request Overview

This PR updates the ICRC-3 specification to clarify how ICRC-1 and ICRC-2 blocks should be handled, specifically establishing that these legacy blocks must not include a btype field and providing concrete examples of account representation.

Explicitly requires ICRC-1/ICRC-2 blocks to omit the btype field, maintaining backward compatibility
Adds detailed examples of account representation as arrays with owner principal and optional subaccount
Updates the burn block schema to align with the legacy format requirements

standards/ICRC-3/README.md

Co-authored-by: Copilot <[email protected]>

…eraction with other standards

…crc-3update

standards/ICRC-3/README.md

Co-authored-by: Andrea Cerulli <[email protected]>

…crc-3update

standards/ICRC-3/README.md

q-uint

We're currently writing some (internal) libraries for ICRC3, would be great to have this merged!

Request: would be great to have a test suite which can just be a list of valid blocks.
I.e. burn, 1burn, mint, 1mint, etc. (maybe separated by generic/legacy).

Thanks for the work!

standards/ICRC-3/README.md

…ites

bogwar · 2025-09-18T13:39:20Z

We're currently writing some (internal) libraries for ICRC3, would be great to have this merged!

Request: would be great to have a test suite which can just be a list of valid blocks. I.e. burn, 1burn, mint, 1mint, etc. (maybe separated by generic/legacy).

Thanks for the work!

Thanks for the comments!

Could you be a bit more specific about the form of such a test suite?

According to the current version of the standard there should be no 1burn btype, but rather this type would need to be inferred from the form of the generic blocks.

q-uint · 2025-09-18T16:49:30Z

Hi @bogwar, sorry the 1burn was a typo.

It seems that currently we are going to need to support both legacy and the new block log types. As this gets somewhat confusing, it would be nice to have a test suite with examples of each of these Value block types.

Personally I don't need these anymore, but it was a lot of work to construct tests which cover all possible flavors of block types. In the end we just ran the indexer against an SNS ledger to battle test it.

q-uint · 2025-10-09T09:42:18Z

Thanks for your time and work on this @bogwar! We're working toward supporting ICRC3 on non-ledger canisters, and your updates make the event log design clearer and more suitable for generic use cases.

q-uint · 2025-10-13T07:13:13Z

I don't want to block this PR from being merged but while applying ICRC-3 to our internal event log I encountered some 'blockers'.

`Value` type

tuple support?
bool support?
null support?
(Optional) principal support?

This is how I currently circumvent this:

impl ICRC3Value for Principal {
    fn to_value(&self) -> Value {
        // This is ok, since principal is a "blob".
        Value::Blob(self.as_slice().to_vec().into())
    }
}

impl ICRC3Value for bool {
    fn to_value(&self) -> Value {
        Value::Nat(Nat::from(*self as u8))
    }
}

Currently we can only support optional values in Map since this allows you to leave them out, yet we can not do the same in, i.e., Array, to represent tuples.

bogwar · 2025-10-13T09:14:35Z

Thanks Quint!

On extending Value:
Value was intentionally minimal (the design was entirely ledger-driven). I’d prefer to keep it that way unless there’s a strong, recurring need.

Principals / bools:
Encoding principals as Blob is fine; bool as Nat 0/1 is also reasonable.

Tuples with optionals:
The tricky case is tuples containing opt. Two workable patterns:

Prefer Maps over tuples when fields can be optional (omit absent fields).
If you must keep array/tuple semantics, use a tagged option per slot: None = [Nat 0], Some(x) = [Nat 1, x].

I’d suggest we keep Value unchanged and add a non-normative “Common Encodings” section with these recommendations (principal→Blob, bool→Nat 0/1, options in tuples via tags). That preserves minimalism while giving interoperable guidance. WDYT?

bogwar · 2025-10-16T15:13:06Z

@q-uint Hi Quint, can you please take a look? I've added a non-normative section with encodings.

letmejustputthishere · 2025-10-22T12:59:25Z

standards/ICRC-3/README.md

 - "2approve" for `icrc2_approve` blocks


 ### Account Type


i still think it would be valuable to have a Principal variant in the Value. this way there is no ambiguity on how to interpret arrays

standards/ICRC-3/README.md

…guarantees

gregorydemay

Thanks @bogwar For revamping this! Some understanding questions and minor comments. Happy to discuss offline if that helps.

gregorydemay · 2025-11-27T13:51:55Z

standards/ICRC-3/README.md

   |         Block i         |          |         Block i+1       |
   ├─────────────────────────┤          ├─────────────────────────┤
 ◄──| phash = hash(Block i-1) |◄─────────| phash = hash(Block i)   |
   | ...                     |          | ...                     |


Should the diagram maybe mention the other mandatory fields (like ts)?

The focus of the diagram is on the chaining aspect; I would keep it like this.

gregorydemay · 2025-11-27T14:01:56Z

standards/ICRC-3/README.md

+
+Typed blocks that **do not** represent method calls (e.g., upgrade markers, maintenance events, migration records, or system actions) MAY omit the `tx` field entirely and therefore MAY omit `tx.op`.
+
+Legacy ICRC-1/2 blocks continue to use their historical operation names (`"xfer"`, `"mint"`, `"burn"`, `"approve"`), and are exempt from namespacing requirements.


I don't understand this part. Those names come from our implementation of the ICRC ledgers, but AFAICT they are not mentioned anywhere in the ICRC-1 or ICRC-2 standards? In fact ICRC-1 only mentions the notion of block as being excluded, while ICRC-2 does not talk about blocks at all.

gregorydemay · 2025-11-27T14:06:35Z

standards/ICRC-3/README.md

+If a block represents the result of a **standardized user-initiated method call**, then:
+
+- The block **SHOULD** include a `tx` field.
+- For user-initiated blocks, a namespaced `tx.op` **SHOULD** be included (see above).


Understanding question: what's the difference betweentx.op and btype? Is-it because a btype block could be produced by several user endpoints?

gregorydemay · 2025-11-27T14:12:14Z

standards/ICRC-3/README.md

+     which fields affect the meaning of the block and how extra fields are to be
+     treated (e.g., ignored by generic interpreters).
+
+3. Derive pre-fee state transition  


I don't really understand this part (also apply fee below), which seems ledger specific (it talks about fees) but that whole section ( Semantics of Blocks: Evaluation Model) should be domain-agnostic way, no?

gregorydemay · 2025-11-27T14:18:56Z

standards/ICRC-3/README.md

+
+### `icrc3_get_blocks`
+Returns blocks for one or more requested ranges from the canonical block log.
+Blocks that are no longer stored locally by the producer are returned indirectly via archive callbacks.


is-it correct that the callback is not-necessarily an ICRC-3 compliant method?

gregorydemay · 2025-11-27T14:26:04Z

standards/ICRC-3/README.md

+  - pre-fee state transition,  
+  - fee payer (if applicable),  


This seems ledger specific

gregorydemay · 2025-11-27T14:26:54Z

standards/ICRC-3/README.md

+- **Describe how fees are handled**, if the block type involves fees:  
+  - The standard **SHOULD** specify the **effective fee** (the fee that is
+    actually charged), where this is well-defined.  
+  - The standard **SHOULD** specify the **fee payer**, as an expression
+    resolvable from fields in the block, where this is possible.  
+  - If applicable, the standard **MAY** reference ICRC-107 to specify **where
+    the fee goes** (e.g., burned, sent to a collector, etc.).  
+  - If some fee-related aspects are intentionally left implementation- or
+    ledger-defined, the standard SHOULD say so explicitly.


This seems ledger specific

gregorydemay · 2025-11-27T14:28:36Z

standards/ICRC-3/README.md

+### Note on Fees
+
+ICRC-3 standardizes how fees are recorded in blocks, but it does not prescribe how fees are
+calculated or collected.
+
+- Every standard that introduces a block type involving fees **SHOULD** specify who the
+  fee payer is and, where possible, how the effective fee is determined, so that
+  responsibility is unambiguous.  
+- Where this cannot be expressed generically (for example, because the policy is
+  intentionally ledger-defined), the standard SHOULD state that the fee payer and/or
+  fee amount are implementation- or ledger-specific.  
+- The rules for interpreting the amount and destination of fees MAY be delegated to
+  ICRC-107 (Fee Handling in Blocks). Ledgers that do not yet implement ICRC-107 MAY
+  still produce valid ICRC-3 blocks, but their fee behavior will remain
+  implementation-specific until aligned with ICRC-107.


Seems ledger specific

gregorydemay · 2025-11-27T14:29:28Z

standards/ICRC-3/README.md

+An ICRC-3 compatible producer canister MUST expose an endpoint listing all the supported block types via the endpoint `icrc3_supported_block_types`.
+
+- For **typed** blocks, the producer canister MUST only produce blocks whose `"btype"` value is included in this list.
+- For **legacy** ICRC-1/2 blocks (no `"btype"`), the producer canister MUST include the conventional identifiers (e.g., `"1xfer"`, `"2approve"`) in this list to advertise support, even though the blocks themselves do not carry a `"btype"` field.


Similar comment as above, I don't see in which standard those are specified.

gregorydemay · 2025-11-27T14:33:24Z

standards/ICRC-3/README.md

+
+
+
+## [ICRC-1](../ICRC-1/README.md) and [ICRC-2](../ICRC-2/README.md) Block Schema


Understanding question: why are we trying to retrofit our ICRC-1 and ICRC-2 implementations into the new ICRC-3 standard? Why not just say that the ledger X is ICRC-3 compliant starting block b and verifying past blocks < b involves knowing the implementation (which is needed anyway and describe din this section but should not maybe be part of ICRC-3)

account examples, no btype for legacy blocks

d8bbe07

bogwar requested a review from Copilot August 6, 2025 18:58

Copilot AI reviewed Aug 6, 2025

View reviewed changes

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

bogwar and others added 7 commits August 6, 2025 21:00

Update standards/ICRC-3/README.md

6e85916

Co-authored-by: Copilot <[email protected]>

Update standards/ICRC-3/README.md

ce7be73

Co-authored-by: Copilot <[email protected]>

added principles of recording transactions in blocks and extended Int…

c0201b0

…eraction with other standards

introduced a section on kinds of blocks

d4d5856

added guideliness for defining blocks/cannonical mappings

825f3f1

Merge branch 'bw/icrc-3update' of github.com:dfinity/ICRC-1 into bw/i…

1091df4

…crc-3update

core state transition, bypte vs tx

9f7a603

mbjorkqvist reviewed Aug 29, 2025

View reviewed changes

bogwar added 2 commits September 1, 2025 13:03

typos

79018dc

minor changes

4e88917

bogwar changed the title ~~account examples, no btype for legacy blocks~~ ICRC-3 refinment Sep 2, 2025

bogwar changed the title ~~ICRC-3 refinment~~ ICRC-3 refinement Sep 2, 2025

mbjorkqvist reviewed Sep 3, 2025

View reviewed changes

standards/ICRC-3/README.md Show resolved Hide resolved

fixed some corner cases

164f310

andreacerulli reviewed Sep 5, 2025

View reviewed changes

bogwar and others added 4 commits September 5, 2025 17:18

Update standards/ICRC-3/README.md

ec99a9d

Co-authored-by: Andrea Cerulli <[email protected]>

timestampe is nanoseconds

570e13c

Merge branch 'bw/icrc-3update' of github.com:dfinity/ICRC-1 into bw/i…

797aa1d

…crc-3update

removed the consolidation section

231779c

maciejdfinity reviewed Sep 9, 2025

View reviewed changes

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

maciejdfinity reviewed Sep 10, 2025

View reviewed changes

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

maciejdfinity reviewed Sep 10, 2025

View reviewed changes

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

maciejdfinity reviewed Sep 10, 2025

View reviewed changes

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

clarified tx.op includes standard number

d2e6f3e

q-uint reviewed Sep 16, 2025

View reviewed changes

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

standards/ICRC-3/README.md Outdated Show resolved Hide resolved

bogwar added 2 commits September 18, 2025 14:43

promoted effective fee to a first class citizen; minor typos and rewr…

df78e30

…ites

minor changes

f4fd592

q-int's comment & fix transfer from based mints semantic

35f2c3f

bogwar added 7 commits October 7, 2025 16:17

make the standard about an event log

45a4b8e

spelled out the generic aspect

5d9c8d8

language ledger agnonstic

6251107

relaxed core state transition

f4a5211

relaxed the btype/tx recommmendations

06ae958

explicit demand that tx captures the user's call

1f12fa2

use producer canister throughout

85bf500

bogwar added 5 commits October 13, 2025 12:08

added back

dbbfcb4

semantics for top level ts

460bb51

added one more example, removed a spurious line

a96fbca

Nat64 --> Nat

f987387

non-normative section with encodings of bools and optionals

a495e4f

letmejustputthishere reviewed Oct 22, 2025

View reviewed changes

bogwar added 9 commits November 19, 2025 16:21

draft methods section

71bda9d

semantics for the remaining methods, small fixes

abacc47

clearer gudiance on user calls, clearer language on icrc3_get_blocks …

ef6013d

…guarantees

further clarifications on tx, tx.op etc

a974a97

refined Semantics of Blocks section

7fe04c6

refined Namespacing for Operations

2476490

removed duplicate sections

bb53670

minor rewording

cd0374c

Candid spec

6194432

gregorydemay reviewed Nov 27, 2025

View reviewed changes


		Typed blocks that do not represent method calls (e.g., upgrade markers, maintenance events, migration records, or system actions) MAY omit the `tx` field entirely and therefore MAY omit `tx.op`.

		Legacy ICRC-1/2 blocks continue to use their historical operation names (`"xfer"`, `"mint"`, `"burn"`, `"approve"`), and are exempt from namespacing requirements.




		## [ICRC-1](../ICRC-1/README.md) and [ICRC-2](../ICRC-2/README.md) Block Schema

ICRC-3 refinement #199

Are you sure you want to change the base?

ICRC-3 refinement #199

Conversation

bogwar commented Aug 6, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

q-uint left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

bogwar commented Sep 18, 2025

Uh oh!

q-uint commented Sep 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

q-uint commented Oct 9, 2025

Uh oh!

q-uint commented Oct 13, 2025

Value type

Uh oh!

bogwar commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bogwar commented Oct 16, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

gregorydemay left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

q-uint left a comment •

edited

Loading

q-uint commented Sep 18, 2025 •

edited

Loading

`Value` type

bogwar commented Oct 13, 2025 •

edited

Loading