import { instructions } from './reference/instructions.js'; import { expressions } from './reference/expressions/expressions.js' import Api from '../src/components/Api.js';
Archetype assets provide a high-level abstraction to handle collection of structured data.
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.
This section presents the application programming interface of an asset collection. Follow an item's link for a detailed presentation.
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();
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);
It is possible to specify relations between assets of two collections with asset field types partition and aggregate.
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.
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.