What massa.ts exposes

[damip]

As defined in massa.ts

data storage

TODO intro

Note that all the following functions also have an equivalent _for-postfixed version with "for_address" as 1st parameter: they execute the base function from the point of view of another SC defined by for_address.

data_set

Sets an entry in the datastore of the current address.
If the entry exists, it is overwritten.

Gas cost

TODO formula (also let's define how storage costs work)

• Roughly: constant + (linear on key length) + (linear on value length)

Parameters

• key: string key of the entry
• value: string to set

Returns

Nothing

data_get

Gets an entry.

Gas cost

TODO formula

• Roughly: constant + (linear on key length) + (linear on value length)

Parameters

• key: string key of the entry

Returns

The found value, or err if not found

data_contains_key

Checks if an entry exists

Gas cost

TODO formula

• Roughly: constant + (linear on key length)

Parameters

• key: string key of the entry

Returns

True if found, False if not found

data_remove

Removes an entry.

Gas cost

TODO formula

• Roughly: constant + (linear on key length)

TODO define reclaimed space

Parameters

• key: string key of the entry

Returns

Boolean: True if something was effectively deleted

Followup Ideas

Optional return values

Having enumerable return values (equivalent of Option or Result in rust) that can be mapped to an error throw (not well supported in AS yet) or a null value by massa.ts can be useful.

This can be implemented for example by returning a formatted string or JSON-serialized object from the ABI and processing it in massa.ts to translate it into a value | null for example

Example; in massa.ts:

export function get_data(key: string): string | null {
    let ret = assembly_script_get_data(key);
    if ret[0] == '1' {
        return ret.slice(1);
    }
    return null;
}

[damip]

We will also have to add things like:

• time()
• random()
• send_message() // for async
• maybe a getter for more context (e.g. slot, block information)
• classes to easily manipulate slots etc...
• crypto tools (hash, signature, key gen etc...)

[z80dev]

Handling "Missing" Data from a Smart Contract

We want a smart contract to be able to attempt interact with data that may not exist yet without risk of the transaction failing. Some example use-cases:

• Checking the token balance for a user who has never received this token
• Checking a token allowance for a user who has not set one for the given spender

Currently, calling get_data with a key for which there is no value leads to the following error:

RuntimeError: Data entry not found

At its core, the problem is that currently, a smart contract has no way of checking if a key already has a value except by calling get_data, and this fails execution if no value is present without giving the smart contract any way of handling the error.

Potential Solution: Implement has and Return Default Value

From the smart contract, we should allow the developer to specify a default value to be returned in case of a failed lookup. This default value should be specified by the caller of get_data. This allows a smart contract to contain code such as:

export function balanceOf(address: string): u32 {
    const key = "bal_" + address;
    return U32.parseInt(get_data_or_default(key, "0"));
}

The simplest way to accomplish this begins by implementing a has(key): boolean function in the ABI. This function provides the base functionality needed (checking if a key has a value) for implementing get_value_or_default(key, defaultVal).

// in massa.ts

export function get_value_or_default(key: string, value: string): string {
    if (has(key)) {
        return get_value(key);
    } else {
        return value;
    }
}

The simplest way to do this I think is by enabling has(key) returning a boolean, so the contract can simply check first. This lets us avoid options, null union types, wrapping classes, etc.

We can implement this in AS with minimal changes to the existing Rust code, and only a small, simple addition to the Rust side(the has function), keeping all this new default value functionality encapsulated to the AS lib. This is another positive in my opinion, Rust has proper Optionals and other ways for us to handle errors, and we don't need this "default value" concept to leak into the Rust code where it is not really needed. However I am still gaining an understanding of the execution engine so I could be wrong about this last point.

Edit:

This requires more discussion, but I think this "default value" lookup will be very very common, and very rarely would a smart contract developer want their contract to fail if they lookup a key which does not exist. This is a bigger design decision, but I think it makes sense for get_data to adopt this behavior entirely on the AS side, instead of making a new method for this.

This will encourage safer smart contracts also. It will force developers to always have to consider the failure case of missing data, and give them an easy way to handle it, by allowing them to specify what to return in this case. It enables the contract to decide for itself how to handle this case of missing data, rather than having the platform make a decision and force it on them.

[damip]

Sounds good to me !

[damip]

ABI issues:

• Massa node side: Add has_data(key) -> bool ABI #2129
• Runtime side: Add has_data(key) -> bool ABI massa-sc-runtime#68

[damip]

ready

[z80dev]

Provide Hashing Primitives

We should expose the ability to run the same hashing algorithms the execution engine runs within smart contracts. For example, if I have a string in my smart contract, and want to calculate the hash of it that will be used as a key in storage, I should have sha256 and base58 functions I can call.

Currently, there are no easy-to-use SHA256 or base58check packages for AssemblyScript. The ones that exist are mainly assemblyscript implementations packaged to be used from javascript and do not integrate easily with the assemblyscript compiler.

The main reason this is currently needed is because set_data expects its key argument to be a valid checksummed base58 hash. Constructing one manually from assemblyscript has been difficult.

[damip]

Good points.

• Add hash, verify, address_from_public_key ABIs #2132
• make get_data and set_data ABIs use non-pre-hashed data #2134

[damip]

ready