ARC-0031: Improving mappings

[evanmarshall]

---

arc: 0031
title: Improving mappings
authors: evan@demoxlabs.xyz, mike@demoxlabs.xyz
discussion: ARC-0031: Improving mappings
topic: Language
status: Draft
created: 10-05-2022

Abstract

Mappings are how Aleo programs store public state. To make them more useful, we should:

1. Load the value of mappings directly.
2. Set the value of mappings directly.
3. Support structs & strings as mapping data types.

Specification

1. A function should be able to load the value of a mapping directly.

mapping balances:
    key owner as address.public;
    value amount as u64.public;

function get_balance:
    input r0 as address.public;
    load balances[r0] into r1;

    output r1 as u64.public;

2. A finalize statement should support setting the value of a mapping directly

mapping balances:
    key owner as address.public;
    value amount as u64.public;

function set_balance:
    input r0 as address.public;
    input r1 as u64.public;

    finalize r0 r1;

finalize set_balance:
    input r0 as address.public;
    input r1 as u64.public;

    set balances[r0] r1;

3. Mapping should support structs

struct nft:
    id as u64.public;
    collection_id as u64.public;
    url as string.public;
    metadata as string.public;

mapping nft_owners:
    key owner as address.public;
    value nft_item as nft.public;

function mint_nft:
    input r0 as address.public;
    input r1 as u64.public;
    input r2 as u64.public;
    input r3 as string.public;
    input r4 as string.public;

    cast r1 r2 r3 r4 into r5 as nft;

    finalize r0 r5;

finalize mint_nft:
    input r0 as address.public;
    input r1 as nft;

    set nft_owners[r0] to r1;

Dependencies

This will impact snarkVM and everything that has snarkVM as a dependency.

Backwards Compatibility

As this is a new feature, no programs should be impacted by adding a new opcode.

Security & Compliance

There should be no regulatory concerns.

[collinc97]

Thanks @evanmarshall 🙌 this is definitely a desired feature for Aleo instructions.

On naming, I like load for the read operation. But set for write feels strange to me personally.
Taking inspiration from other assembly languages like MIPS, store feels more natural.

finalize mint_nft:
    input r0 as address.public;
    input r1 as nft;

    store nft_owners[r0] to r1;

I think we should gather more thoughts from the community to increase confidence in either direction.

[evanmarshall]

I think you make a good point and it should be store instead.

[d0cd]

+1

[d0cd]

To preserve consistency with existing syntax, I think store should be expressed as:
store account[r0] r1;

We also have the option of writing loads and stores as:
load account r0 into r1 and store account r0 r1
which is more consistent with the syntax for call and cast.
This form also has the added benefit of removing the [ and ] tokens from the grammar.
On the other hand, users may find that this syntax is unclear as to which operand is the index into the mapping.

[acoglio]

The notation with [ ] for load and store is consistent with the current one for increment and decrement. On the other hand, we could make all of them (load, store, increment, decrement) consistently not use [ ], which may be more appropriate for an assembly-like language like Aleo instructions. But there's nothing wrong with [ ] of course.

Just to explore all possibilities, here are some "consistent" pairs that we could use as the operation names:

• get and set
• load and store
• read and write

[fulltimemike]

I'm in favor of load and store -- they seem to suggest asynchronicity, and I think these operations affecting mappings will have to occur in the finalize statements, since they'll be "fire and forget". I'm also in favor of the brackets, because they indicate similarity between mappings on aleo and mappings on ethereum.

Another ARC may be more appropriate, but with the support in finalize statements right now, just expanding mappings' functionality as laid out here won't do much to improve what programs are able to do. loading and storeing values may help for incrementing and decrementing, but we should probably allow the full suite of aleo instructions and operations in the finalize statements.

As for this ARC, I'm in favor of it. We may want to specify as well that load and store must take place within the finalize statement, unless we can do those operations in functions and closures too.

[d0cd]

Agreed, we will need to support other instructions in a finalize block as well.
There might be a way for us to support loads in a function block (by providing it as input and checking that it matches the state on chain) but this would likely be a completely new feature.

[d0cd]

Tracking progress here: https://github.com/AleoHQ/snarkVM/pull/1190

[evanmarshall]

One other note, we should add support to the REST API to support getting the value of a mapping for a particular key.

[arosboro]

for a particular key, it would also be nice to increment a key on a stored struct. Like as follows:

struct word_count {
    class_1_freq: u64,
    class_2_freq: u64,
}
mapping word_counter: string => word_count;
...
increment_property word_counter "foo" class_2_freq 1u64;