Asset

Archetype assets provide a high-level abstraction to handle collection of structured data.

Introduction

Similarly to a SQL table, an asset is a collection of data, stored in the contract storage, organized in rows and columns and defined by an identifier and a list of fields.

An asset collection provides a set of instructions to manage the collection, and expressions to interrogate the collection (see API section below for more information).

For example, the following declaration defines a collection of loan data:

asset loan identified by id {
  id         : string;
  subscriber : address;
  principal  : tez;
  interest   : rational = 2%;
  creation   : date     = now;
  delay      : duration = 10w; /* 10 weeks */
}

The declaration above creates a collection of loans; each loan is defined by a string identifier id and five data fields (from subscriber to delay). Note that fields may have a default value.

Refer to the declaration section for more information.

API

This section presents the application programming interface of an asset collection. Follow an item's link for a detailed presentation.

Instructions

---

add

Adds a new asset in collection

---

put

Adds or replace an asset in collection

---

update

Updates one or several fields of an asset in collection

---

update_all

Updates one or several fields of an asset collection or view

---

add_update

Adds a new asset or updates an asset in collection

---

remove

Removes element from collection, partition or aggregate

---

put_remove

Puts or removes an element in collection

---

remove_if

Removes referenced assets that verify a predicate

---

remove_all

Removes all assets from collection

---

clear

Removes all referenced assets from an asset view

Expressions

---

[]

Gets asset record value from key

---

[].

Gets an asset field from key

---

[]?.

Gets an option of asset field from key

---

contains

Tests whether the collection contains an asset

---

count

Returns the number of assets in collection

---

nth

Returns nth element in collection

---

sort

Sorts assets according to a field

---

sum

Sums values of asset field

---

select

Selects assets that verify a predicate

---

head

Returns first assets

---

tail

Returns last assets

---

to_container

Returns collection as basic container

Utility types

---

asset_key<A>

Type of the asset identifier

---

asset_value<A>

Type of the asset data

---

asset_container<A>

Type of the asset collection

---

asset_view<A>

Read-only collection of assets

Utility builtins

---

make_asset

Creates an asset object from key and value

A convenient aspect of this API is the possibility to combine expressions and instructions. For example, consider the following vehicle asset definition:

asset vehicle {
  vin          : string;
  nbrepairs    : nat  = 0;
  dateofrepair : date = now;
}

The following one line code removes the top 3 recently repaired vehicles with total number of 2 repairs:

vehicle.sort(dateofrepair).select(the.nbrepairs = 2).head(3).remove_all();

Iteration

An asset collection is iterable with the for k in ... do ... done loop instruction.

For example, the following code iterates on the loan collection:

var total = 0tz;
for k in loan do /* k is a loan key */
  /* do something with asset with key k */
  total += loan[k].interest * loan[k].principal
done

Note that:

• assets are iterated in the natural key order.
• Note also that the above loop instruction is equivalent to the following expression:

var total = loan.sum(interest * principal);

Relations

It is possible to specify relations between assets of two collections with asset field types partition and aggregate.

Partition

A partition defines a one-to-many relation between an asset B (partitioning asset) and an asset A (partitioned asset) so that an asset from collection A is in relation with exactly one asset from collection B; conversely an asset from collection B is in relation with zero, one or many assets from collection A.

The following declarations define asset B with a partition of A, typed partition<A>:

asset A {
  ida : nat
}

asset B {
  idb  : nat;
  pofa : partition<A> /* field 'pofa' is a partition of A */
}

The partition relation is ensured statically by the compiler as it is not possible to add straightforwardly an asset to collection A. It is only possible through the parition field of an asset from collection B in order to ensure the relation is respected:

B[kb].pofa.add({ ka });

See partition section of add and remove instructions for more information.

Aggregate

An aggregate defines a many-to-many relation between an asset B (aggregating asset) and an asset A (aggregated asset) so that an asset from collection A is in relation with zero, one or many assets from collection B; conversely an asset from collection B is in relation with zero, one or many assets from collection A.

The following declarations define asset B with an aggregate of A, typed aggregate<A>:

asset A {
  ida : nat
}

asset B {
  idb  : nat;
  aofa : aggregate<A> /* field 'aofa' is an aggregate of A */
}

Adding a reference (ie. an identifier) in aofa field fails at runtime if the asset is not in collection A.

See aggregate section of add and remove instructions for more information.