ICRC-7 including WG comments and other changes

[dietersommer]

No description provided.

[sea-snake]

// type: leave open for now

This should probably be defined similar to ICRC-1 spec:

The memo parameter is an arbitrary blob that has no meaning to the ledger. The ledger SHOULD allow memos of at least 32 bytes in length.

[dietersommer]

Indeed, this is already in the text below the data structure:

The memo parameter is an arbitrary blob that is not interpreted by the ledger.
The ledger SHOULD allow memos of at least 32 bytes in length.
The ledger SHOULD use the memo argument for transaction deduplication.

Is this what you meant?

[sea-snake]

As mentioned during the meeting, a token could set a high approval limit and/or have large blob sizes in their memo fields.

Currently to get token approvals we have:

icrc7_get_approvals: (token_ids : vec nat)
    -> (vec record { token_id : nat; approvals : vec record { token_id : nat; spender : Account; expires_at : opt nat64; created_at_time : opt nat64; } });

To add support for high approval limits and/or large memo fields, skip take would need to be added.

During this discussion we mentioned that skip take per token id or a batch query call would be complicated because we would have a list of skip take lists, this isn't user friendly.

The first thing that currently comes to mind is considering the query token_ids argument as filter and returning a list of approvals that isn't grouped by token id. In combination with sorting on e.g. created_at_time, one could do a skip take where skip is the created at time. This basically would allow a user to get approvals before/after a specific time (depending on sort order).

icrc7_get_approvals: (token_ids : opt vec nat, skip: opt nat64; take: opt nat)
    -> (vec record { token_id : nat; spender : Account; expires_at : opt nat64; created_at_time : opt nat64; });

This would also allow for more filters besides token_ids so e.g. a marketplace could get all approvals is has received.

icrc7_get_approvals: (opt token_ids : opt vec nat, owner: opt Account; spender: opt Account; skip: opt nat64; take: opt nat)
    -> (vec record { token_id : nat; spender : Account; expires_at : opt nat64; created_at_time : opt nat64; });

If token_ids, owner and spender are all not set, it would return a list of all token approvals within the ledger.

[dietersommer]

As mentioned during the meeting, a token could set a high approval limit and/or have large blob sizes in their memo fields.

Currently to get token approvals we have:

icrc7_get_approvals: (token_ids : vec nat)
    -> (vec record { token_id : nat; approvals : vec record { token_id : nat; spender : Account; expires_at : opt nat64; created_at_time : opt nat64; } });

To add support for high approval limits and/or large memo fields, skip take would need to be added.

During this discussion we mentioned that skip take per token id or a batch query call would be complicated because we would have a list of skip take lists, this isn't user friendly.

The first thing that currently comes to mind is considering the query token_ids argument as filter and returning a list of approvals that isn't grouped by token id. In combination with sorting on e.g. created_at_time, one could do a skip take where skip is the created at time. This basically would allow a user to get approvals before/after a specific time (depending on sort order).

icrc7_get_approvals: (token_ids : opt vec nat, skip: opt nat64; take: opt nat)
    -> (vec record { token_id : nat; spender : Account; expires_at : opt nat64; created_at_time : opt nat64; });

This would also allow for more filters besides token_ids so e.g. a marketplace could get all approvals is has received.

icrc7_get_approvals: (opt token_ids : opt vec nat, owner: opt Account; spender: opt Account; skip: opt nat64; take: opt nat)
    -> (vec record { token_id : nat; spender : Account; expires_at : opt nat64; created_at_time : opt nat64; });

If token_ids, owner and spender are all not set, it would return a list of all token approvals within the ledger.

@sea-snake

This is a good point indeed! As discussed in yesterday's meeting we want to reintroduce pagination for this reason.

Your interface is very generic and nice in terms of what one can do for querying approvals. I really like this API. Is this still sufficiently easy to implement? Let's see how it could be implemented reasonably.

Take the simplest case of allowing for queries for approvals for a list of token_ids where the approvals in the response are sorted by created_at_time, henceforth referred to as time also. All of this with pagination and efficient. Fulfilling those requirements requires a data structure that has indexing over token_id and created_at_time built in, or multiple data structures in orchestration.

icrc7_get_approvals: (token_ids : opt vec nat, skip: opt ApprovalInfo, take: opt nat)
-> (vec record { token_id : nat; approval : ApprovalInfo });

ApprovalInfo contains all the attributes of the approval without the token_id it applies to.

An example of such a data structure could be the following: Keep an index over sorted token_ids, each entry pointing to a tree data structure that contains the approvals for the given token_id, sorted by created_at_time.

Each call being made to retrieve take many approvals for a given list of token ids, starting with the approval following one provided as skip parameter can be implemented efficiently using this data structure. The skip parameter is the most recent approval seen in the previous call to the method. Based on its token_id, we need to obtain approvals following this token_id in a time-sorted manner through the tree data structure for this token_id, and return all the ones following the skip approval. Once all approvals have been enumerated for this token_id, iterate to the next higher token id and enumerate approvals until take many tokens can be provided in the response.

What's not yet addressed here is the case of multiple approvals issued with the same time. As the timestamps have nanosecond granularity, this is likely a non-issue and identical time stamps should not be a practical problem.

All of this is not really rocket science, but also not trivial to implement reliably and efficiently. Further filtering capabilities than in the outlined example, i.e., getting to the general API sketched above, require further indices (efficient) or iteration over possibly large data sets (easier to implement, but inefficient for practical data sets).

What do people think about the complexity of such an implementation? Is this something we can put into the base standard and require everyone to implement?

Also: Should't take be int instead of nat type?

[benjizhai]

While I like the general idea, I would like to point out that created_at_time is an optional field.

According to what we discussed during the WG, the skip-take semantics should just use any arbitrary return item as the non-null value for skip, and the implementation may use any internal sorting order.

[sea-snake]

Changes look good to me, approvals look simple enough for the client to fetch them with prev take while the complexity for implementers has been kept simple :D

[sea-snake]

One small consistency detail that might need to be double checked, some methods have nat32 as take type and some have nat.

[sea-snake]

Collection metadata is still vec value, thus has no keys, I thought the ideas was to make that key value (vec record {text; Value})?

[letmejustputthishere]

the candid doesn't seem to match the text above, i don't see any token_id in the response 🤔

[dietersommer]

Good catch, adapted to match our simplified positional API.

[letmejustputthishere]

how do we handle the case that a token_id does not exist?

[dietersommer]

Added that they should also receive a null response. Non-existing token ids should not be a major error case: We can require that it's everyone's responsibility to query for existing token ids as all the ids used in the API need to come from some source and thus should be valid. Loosing the differentiation between non-existing and no owner listable is thus not a major issue.

[letmejustputthishere]

in general, the more that i'm looking at this the more i'm wondering if we should extract batching into a separate standard as well to keep ICRC7 as simple as possible 🤔

i wasn't around for the last 2 meetings due to calendar conflicts, but would be happy to understand why we reverted to the index based response.

[dietersommer]

in general, the more that i'm looking at this the more i'm wondering if we should extract batching into a separate standard as well to keep ICRC7 as simple as possible 🤔

We can discuss tomorrow, but as far as I remember, we have discussed already and wanted to have the basic API be a batch API.

i wasn't around for the last 2 meetings due to calendar conflicts, but would be happy to understand why we reverted to the index based response.

The new positional API is much simpler and saves space in the response value. Also, it simplifies by removing the top-level error. All of this makes the API much simpler. Also, some requirements like that of all request items must be responded to in the response has been omitted as it was complicating the implementation.

And the new API is aligned with the ICRC-4 standard on batch methods for fungible tokens. The ideas came up in this context and were then brought over to here.