Nano contracts: how it works

info

Nano contracts feature is being progressively rolled out but is still in beta testing, and currently only available on nano-testnet.

Introduction

This article explains how the nano contracts feature works. Understanding this functioning is essential to anyone implementing nano contracts into a use case.

Architecture

The following diagram illustrates the architecture of the nano contracts feature:

This diagram depicts two elements of a full node: the source code of a Hathor client, and the copy of Hathor blockchain (i.e., the ledger). Let's detail what (concerning the nano contracts feature) is inside each of these two elements.

Hathor client (source code)

In the conventional smart contracts approach (as seen in Ethereum platform), each contract registered on chain has its own source code and state. Conversely, on Hathor, a nano contract registered on chain does not have its own source code. Rather, each nano contract instance has its state and a reference to a blueprint.

A blueprint is the source code used to model multiple use cases, from which nano contracts are instantiated. In other words, all nano contracts referencing the same blueprint share the same source code.

A blueprint has attributes and methods that model the behavior of the nano contracts instantiated from it. Hathor platform provides a set of built-in blueprints, which make up a catalog. Additionally, any user can register a blueprint on chain. And then, any user can employ any of these blueprints to create new contracts.

The left side of the diagram, within the Hathor client, shows the representation of the blueprints and the catalog they comprise. In the blueprint catalog, we can see all the built-in blueprints available on Hathor platform for contract creation. Further to the left, we see the representation of the source code for one of these blueprints, in this case, the liquidity pool.

Hathor blockchain (ledger)

On the right side of the diagram, we have Hathor blockchain. Within it, the representation of all registered blueprints, all registered contracts, and alongside, all transactions related to each of these contracts.

A nano contract recorded on chain is defined by:

• a unique id;
• a reference to a blueprint (either built-in or on-chain); and
• a state

Still on the right side of the diagram, one can see in instance A the representation of these elements. The arrow extending from instance A to the left side of the diagram represents that this nano contract references the liquidity pool blueprint. In this instance, we also see the contract's stored state.

Finally, we see a linked list of transactions representing all transactions recorded on Hathor blockchain related to this nano contract. The first transaction is the one that created the contract, and all subsequent ones execute the contract.

Differently from conventional smart contracts, when creating a new nano contract, a user does not provide the source code of the contract. Rather, they select a blueprint, and provide all data that such blueprint needs to initiate its first state. This is done by submitting to the blockchain a transaction to create a nano contract.

Anatomy

The following diagram depicts the anatomy of a nano contract:

A nano contract has a unique id and an instance of a blueprint class, which includes attributes and methods. Additionally, it has a multi-token balance. The values of its attributes, combined with the multi-token balance, constitute the state of the contract.

Multi-token balance

Just like a regular wallet, a contract can hold any amount of multiple different tokens and authorities, which together comprise its multi-token balance. The contract is both the owner and custodian of the multi-token balance and any deposit or withdrawal is authorized by it. However, this multi-token balance is not one of its attributes.

This is a key difference between Hathor and Ethereum or other EVM-compatible blockchains. The Ethereum platform only manages the balance of the native token ETH, while the balances of other tokens are stored as contract attributes and managed directly by the contract that issued them. In turn, on Hathor all built-in custom tokens function as native tokens. Then, Hathor platform directly manages the balance of all tokens, just it does with HTR.

Attributes

A contract has a set of attributes. With the exception of the multi-token balance, all other contract data is stored as attributes. During its execution, a contract can change the value of its attributes but cannot directly change its balance. Instead, it authorizes or denies the entire set of actions requested by the caller, which can be a user (via transactions), or another contract (via call chains).

A contract may specify which tokens it can transact with in its attributes. For example, contract ABC might specify in its attributes that it only authorizes deposits in tokens A, B, and C, limiting its multi-token balance to these tokens. Conversely, contract CDE might not restrict its operations to specific tokens, potentially authorizing deposits in any token registered on Hathor blockchain.

State

The set of all attributes of a contract, with their respective values in a given moment, combined with its multi-token balance, defines the state of the contract. Hathor blockchain (ledger) keeps the state of all recorded contracts. This means that Hathor uses the world state model for contracts bookkeeping.

note

For more on the bookkeeping model of Hathor, see Bookkeeping model at encyclopedia

Methods

Blueprints, and as a consequence, nano contracts, have three types of methods¹:

• Public methods
• View methods
• Internal methods

In addition, there are also two unique predefined methods:

• initialize
• fallback

Public methods

Public methods are used to create or execute a contract. A smart contract is a program that runs only when called. Thus, executing a contract means executing one of its public methods in order to change its state. In other words, they provide the functionalities of the contract to callers. A contract caller can be a wallet (user) or another contract.

Public methods are the only methods whose execution may result in changes to the contract state. Although not mandatory, in most cases, it is expected that the successful execution of a public method results in changes to the contract's state. In turn, a change in a contract's state is always the result of its execution.

Public methods do not directly change the contract's balance. This means that they don't contain statements that increase or decrease the amount of tokens the contract holds. Instead, they only authorize or deny the deposits and withdrawals requested by callers, and it is up to Hathor engine to perform them.

Public methods are called by wallets (users) from a nano contract transaction submitted to Hathor Network, and by other contracts during the execution of a public method.

For example, suppose a certain contract registered on Hathor blockchain has a functionality to provide loans. This contract has the public method request_loan which, when called, will evaluate and authorize or deny a user's loan request. To execute this contract, Alice submits a nano contract transaction to Hathor Network calling the public method request_loan. During its execution, this method may change the values of any of its attributes and will authorize or deny the loan, which is requested as a withdrawal from the contract's balance. These changes in the attributes and the contract's balance are what we refer to as changes in the contract's state.

info

To reiterate:

• Public methods are utilized by callers to create or execute nano contracts.
• To utilize the functionality of a contract, a caller needs to call the respective public method.
• To call a public method, a wallet needs to submit to Hathor Network a nano contract transaction requesting the call; and a contract needs to call it during the execution of one of its public methods.
• Public methods cannot directly change the contract's balance; in fact, no method can directly change the contract's balance.
• Public methods can change their contract's attributes.
• During execution, public methods update the contract's attributes and authorize or deny Hathor engine to perform the entire set of actions requested by the user.

View methods

View methods perform logic whose only effect is their return value and serve other methods, other contracts, and Hathor users. They can be called internally by another method of the contract itself, or by another method of other contracts. They can also be called by users via the Hathor full node API for querying purposes.

View methods cannot change the state of the contract. They can be used to handle part of the business logic of the contract, as long as they do not attempt to change the contract's attributes.

View methods are used to provide information that is not directly available in the contract's state but can be computed and returned ad hoc to users and other contracts.

For example, consider that the loan contract has a public method request_loan and a view method assess_credit. If Alice wants to request a loan, she submits a nano contract transaction that calls request_loan with her loan details and credit information. During execution, request_loan calls assess_credit to evaluate Alice's credit and decide whether or not should provide the loan. Now, if Alice wants to check her credit conditions before making the loan request (a public method call), she can use a full node API request to directly call assess_credit.

info

To reiterate:

• View methods are utilized by the contract to implement part of its business logic, and by users and other contracts to obtain information not directly available in the contract's state.
• View methods cannot be called from blockchain transactions.
• View methods can be called internally by other methods and contracts, and externally by users via the full node API.
• View methods cannot change the contract state.
• The only effect of a view method execution is its return value.

Internal methods

Internal methods are used as helpers to implement internal logic of the contract. They are not externally accessible: they cannot be called by wallets via transactions, by other contracts via call chains (as public methods can), or via full node API requests (as view methods can). They can only be called internally by other methods within the same contract.

For example, the loan contract might have an internal method authorize_loan, which is called during the execution of the public method request_loan. It will receive as parameters Alice's credit profile, generated by assess_credit, and should return TRUE or FALSE to authorize or deny the loan. In this way, since assess_credit is a view method, Alice may query it before applying for a loan to know her credit profile and her chances of getting the loan. However, since authorize_loan is internal, only during the execution of request_loan will Alice find out whether her loan will be authorized or not.

info

To reiterate:

• Internal methods are utilized internally by the contract itself to implement part of its business logic.
• Internal methods cannot be called from blockchain transactions like public methods.
• Internal methods cannot be called from the full node API like view methods.
• Internal methods cannot be called by other contracts.
• Internal methods can only be called internally by other methods of the contract itself.

Method initialize

initialize is the public method of a blueprint used to create a new contract. Every blueprint must implement exactly one initialize method. The execution of initialize marks the beginning of a contract's lifecycle, and it is never used again within that contract. In other words, the initialize method is called on the blueprint, but never on an individual contract.

Method fallback

fallback is the method that is invoked when a call is made to a non-existent public method in the contract. Like initialize, fallback is a unique method with a predefined behavior. However, unlike initialize, which is mandatory for every blueprint, fallback is optional. The blueprint developer may choose whether or not to implement it. If present, like initialize, there can be only one fallback method.

Suppose a contract does not have method fallback. In this case, if one calls a public method that does not exist in that contract, the call fails. Now, suppose a contract does have method fallback. In this case, if one calls a public method that does not exist in that contract, Hathor engine invokes method fallback instead.

Finally, fallback is not of type public, view, or internal. Therefore, it cannot be called directly in any way, neither by external callers nor by the contract itself. It is invoked only by the Hathor engine, and only in the specific case previously described: when a caller attempts to call a non-existent public method.

Transactions

A nano contract transaction (also known as an NC transaction) is a type of transaction that triggers the creation or execution of one or more contracts. An NC transaction includes a call to a public method of a contract. This call serves as the entry point for a call chain involving public and view methods of any contracts, as well as initialize methods of any blueprints. The following diagram depicts the anatomy of a nano contract transaction:

Entry point

When creating an NC transaction, there are four fields that a wallet (user) must provide that do not exist in other types of transactions:

• blueprint_id
• contract_id
• method
• args

These fields together define the entry point. The entry point is the call to an initialize method of a blueprint or another public method of a contract described in the NC transaction.

This call may end without calling any other methods, or it may call public and view methods from other contracts and initialize from blueprints. From there, the process continues, forming a call chain.

blueprint_id

In Hathor, every DAG vertex, block, transaction, token, blueprint, and contract, is identified by a 32-byte UUID. blueprint_id is the identifier of the blueprint that will be used in the public method call described in the transaction.

contract_id

contract_id is the identifier of the contract that will be executed in the public method call described in the transaction. If the call is for contract creation, then this field is empty.

method

method identifies the method of the blueprint that will be invoked in the public method call described in the transaction. Each blueprint implements its own set of methods, — according to its own business logic — that dictates how the contract works. There is only one method that is mandatorily implemented in all blueprints: initialize.

args

args is the set of arguments that should be passed in a method call. Each method of each blueprint requires a different set of arguments.

Inputs/outputs → deposits/withdrawals

The set of inputs and outputs of an NC transaction is translated into the set of deposits and withdrawals that a user intends to make to/from a contract. Moreover, it relates solely to the entry point call.

To understand how this translation works, let's compare it with ordinary fund transfers. The following diagram shows the relationship of inputs and outputs in a transaction where Alice transfers 10 tokens A to Bob:

$\text{sum of inputs} == \text{sum of outputs}$

Note that in this case, the sum of the inputs amounts matches the sum of the outputs amounts. This does not happen in NC transactions. Unlike the transfer between Alice and Bob, where Alice consumed a UTXO as input and Bob received a UTXO as output, a user performs deposit and withdrawal actions in a contract. These actions are translated from the difference between the sums of inputs and outputs.

The following diagram shows the relationship of inputs and outputs in an NC transaction where Alice wants to deposit 10 tokens A into a nano contract:

$\text{sum of inputs} - \text{sum of outputs} == 10$

Note that the sum of the inputs is 10 tokens A greater than the sum of the outputs. For a given token, when the sum of inputs is greater than the sum of outputs, it translates as a deposit. Now, suppose Alice wants to withdraw 10 tokens B from a nano contract:

$\text{sum of inputs} - \text{sum of outputs} == -10$

Note that the sum of the outputs is 10 tokens B greater than the sum of the inputs. For a given token, when the sum of outputs is greater than the sum of inputs, it translates as a withdrawal. Now suppose Alice wants to deposit 10 tokens A and withdraw 10 tokens B:

$(\text{sum of inputs A} - \text{sum of outputs A} == 10) \text{ and } (\text{sum of inputs B} - \text{sum of outputs B} == -10)$

Note that a single NC transaction can have none, one, or multiple deposit and withdrawal actions in any combination. Additionally, since the translation into actions is based on the difference in the sum of amounts between inputs and outputs, it is not possible to have two actions related to the same token. In other words, Hathor protocol consolidates all inputs and outputs related to a single token into a single deposit or withdrawal action.

For example, this prevents a scenario where "Alice wants to deposit 10 tokens A into the contract and withdraw 20 tokens A from the contract". In this case, Hathor protocol consolidates that "Alice wants to withdraw 10 tokens A from the contract".

Flow

A nano contract transaction has the following flow:

1. Submission
2. Validation
3. Creation/execution
4. Resolution

The following diagram illustrates the flow of a nano contract transaction:

Credits: icons created by Juicy Fish — The Noun Project, Vectors Tank — Flaticon, Icongeek26 — Flaticon, Soremba — Flaticon, Trevor Dsouza — The Noun Project, Sutriman — The Noun Project, and Soapi — The Noun Project.

Submission

A wallet (user) creates a new NC transaction. In this transaction, it defines the entry point — that is, a call to a single public method that originates an arbitrary long call chain. The entry point can be a call to the initialize method of a blueprint or to another public method of a contract. Then, the wallet submits the transaction to Hathor Network.

Validation

Hathor protocol then begins the validation phase of the transaction. First, the common validations applicable to all transactions are performed. If the transaction passes these validations, the specific validations for NC transactions are then conducted. If the transaction is considered valid, it is added to the mempool, to wait for the next block. At this point, the entry point call has not occurred yet. The entry point call is only processed when the transaction is confirmed by a block.

Creation/execution

When a new block is received, as part of the process of adding the transaction to the ledger, Hathor engine invokes the entry point call specified in the NC transaction.

The entry point call may or may not invoke public and view methods of other contracts, which in turn may do the same, generating the call chain. During the call chain, any number of contracts may be created and executed. However, such changes are not yet confirmed. The entire call chain is an atomic operation; that is, it is marked entirely as success or failure.

For example, suppose Alice wants to obtain a loan of 100 tokens A from a loan contract. To do this, she submits an NC transaction with the request_loan method as entry point call with a request to withdraw 100 tokens A. When invoked for execution by Hathor engine, request_loan performs a credit assessment of Alice to decide whether to authorize the loan request. request_loan does not return an exception, indicating that it authorizes the loan.

Now, suppose Bob wants to obtain a loan of 1000 tokens A from the same loan contract. He then submits an NC transaction with request_loan as entry point call with a request to withdraw 1000 tokens A. When invoked for execution by Hathor engine, request_loan performs a credit assessment of Bob and returns an exception. This indicates that the contract did not authorize the loan.

Resolution

After the call chain ends, the Hathor protocol regains control. At this point, the state changes made during the call chain are not yet reflected in the ledger (blockchain). That is, new tokens and contracts have not yet been created, and the state of existing contracts has not been updated.

If Hathor protocol does not receive an exception as the return value of the entry point call, it records the execution of the call chain in the transaction as 'success'. Then, it commits all changes made and updates the state of the ledger.

Conversely, if Hathor protocol receives an exception as the return value of the entry point call, it records the execution of the call chain in the transaction as 'failure'. In this case, all changes are discarded, and the ledger state remains unchanged.

Note that even so, the transaction will be added to the ledger, because by this point, computing resources have already been consumed by all nodes in the network, thus requiring the calculation and payment of gas fees.

For example, in Alice's case from the previous subsection, request_loan returned nothing to Hathor protocol. Hathor protocol does not know the business logic of the loan contract. All it knows is that request_loan made several updates to its attributes and authorized the completion of the entire set of deposits and withdrawals described in the transaction. In Alice's case, it is a single withdrawal of 100 tokens A. Hathor protocol will then update the attributes in the ledger and subtract 100 tokens A from the contract's balance. Finally, it will add the transaction to the blockchain marked as 'success', formalizing the transfer of 100 tokens A from the contract's balance to Alice's wallet.

In Bob's case, request_loan returned an exception to Hathor protocol. Hathor protocol understands that there was a failure in the contract's execution and that the contract did not authorize the completion of the entire set of deposits and withdrawals described in the transaction. In Bob's case, it is a single withdrawal of 1000 tokens A. Hathor protocol will then discard the changes made during the method's running and will not make any update to the contract's state. Finally, it adds the transaction to the blockchain marked as 'fail', with its inputs/outputs voided.

Ledger entry

As explained in the previous sections, when submitted by a wallet (user) to the network, an NC transaction contains:

• The fields that describe the entry point call.
• Inputs and outputs that describe the deposits and withdrawals the wallet perform to perform on the contract.

After the call chain execution is complete, Hathor protocol adds the following information to the NC transaction:

• Call chain record: a sequence of "public method / contract" pairs that were invoked.
• Call chain status: success or failure of the entire call chain.

Note that when submitting the transaction, the user makes a single call (entry point). However, because the execution of this public method may trigger additional calls, (and this happens recursively) the transaction may end up recording multiple contract creations and executions. With all this information recorded, the transaction is added as a new confirmed entry in the ledger (blockchain).

Life cycle

The following diagram illustrates the life cycle of a nano contract:

Credits: Icon created by SBTS from the Noun Project.

The life of a contract begins with the transaction that creates it. From this point, users and other contracts can read and execute the contract as long as the blockchain network remains operational — in other words, it lasts indefinitely. Contract executions are triggered via transactions and performed in the scope of a call chain, while contract readings are typical readings from the blockchain. Contract executions may either succeed or fail.

The contract life line depicted in the diagram represents the history of a contract. The history of a contract comprises the sequence of all transactions registered in the blockchain related to such contract. That is, all transactions in which a public method of this contract is called in the call chain. The history of a contract always begins with the transaction that created the contract, and proceeds with all valid transactions that attempted to execute the contract — i.e., those that succeeded in executing the contract, and those that failed to execute the contract.

Reading the contract doesn't count as part of the contract history — i.e., if one reads a contract this interactions will not be added to this contract's history. Furthermore, contract creation, execution and reading are the possible interactions that one may have with a contract. In the next section we discuss in detail how these interactions comprise an overall behavior of a nano contract.

Behavior

The behavior of nano contracts can be understood by three viewpoints:

1. Actors: which actors interact with a contract?
2. Interactions: what types of interactions can these actors have with a contract?
3. Actions: how are balance updates performed during interactions between these actors and the contract?

Actors

There are two types of actors that interact with a contract:

• Callers
• Readers

Callers

Callers are all those who call a public method to create or execute a contract. A caller calls the initialize public method of a blueprint to create a contract, or another public method of a contract to execute it.

A caller can be either a wallet or another contract. A wallet calls a contract's public method through the entry point of an NC transaction. A contract can call another contract during the execution of one of its public methods, within the scope of a call chain.

Readers

Readers are all those who only read information about a contract recorded on the ledger (blockchain). A reader can read the contract's state and history through direct ledger access. Additionally, a reader can call a view method to obtain ad hoc information not available in the contract's state.

A reader can be any Hathor user or another contract. A Hathor user can read the contract's state and history, as well as call view methods, via an API request to their full node. A contract can query the state and history, and call view methods of other contracts during its creation or execution, within the scope of a call chain.

Interactions

There are three possible interactions an actor can have with a contract:

• Creation
• Execution
• Reading

Contract creation

Contract creation occurs when a caller calls the initialize method of a blueprint registered on Hathor platform. If the caller is a wallet, the call serves as the entry point of an NC transaction submitted by the wallet. In this case, the transaction’s inputs and outputs will consolidate the set of deposits and authority grants the wallet provides to the contract.

In turn, if the caller is a contract, the call is made within the scope of a call chain initiated by an arbitrary transaction from any wallet. In this case, the contract will specify, as a batch of actions, the deposits and authority grants it intends to provide to the new contract.

As with any public method call, the initialize call should include the appropriate set of arguments and actions required for the method to execute correctly. If contract creation succeeds, a new contract is registered on the network, identified by a 32-byte UUID, and its state is initialized. Finally, the transaction containing the call chain to which this call belongs is recorded as the beginning of the contract’s history.

Let's revisit the loan contract example from the previous subsections. Suppose there is a lending blueprint on Hathor platform that allows the creation of loan contracts. A bank intends to use this blueprint to offer 10 million tokens A for loans. To do this, it must submit an NC transaction to Hathor Network such that:

• blueprint_id references the lending blueprint on Hathor platform;
• method is initialize;
• args provides a set of arguments as defined in this blueprint's specific initialize implementation to set up the loan contract attributes; and
• inputs and outputs consolidates as a batch of actions that in this case, contains a single action: a deposit of 10 million tokens A to fund the contract.

Contract execution

Contract execution occurs when a caller calls a public method of a contract other than initialize. If the caller is a wallet, the call is made by submitting an NC transaction in which the call serves as the entry point. In this case, the transaction’s inputs and outputs consolidate all deposits, withdrawals, and authority grants and acquisitions the wallet intends to perform with the contract.

I turn, if the caller is a contract, the call is made within the scope of an arbitrary call chain. In this case, the contract provides a batch of actions containing all deposits, withdrawals, and authority grants and acquisitions it intends to perform with the called contract.

Every public method call should include the appropriate arguments and actions required by that specific method of the blueprint. If the call chain execution is successful, the caller’s balances are updated, and the state (attributes and balances) of the executed contract is also updated. Additionally, the states of all other contracts executed within the same call chain are updated as well. Finally, the transaction containing the call chain to which the call belongs is recorded in the contract’s history.

For example, to obtain the loan described in the previous subsection, Alice would submit an NC transaction to Hathor Network such that:

• blueprint_id points to the specific loan contract registered on Hathor ledger;
• method calls the request_loan method;
• args provides the set of arguments as defined in this blueprint's specific request_loan implementation to evaluate Alice's credit conditions; and
• inputs and outputs consolidates a batch of actions that in this case, contains a single action: a withdrawal of 100 tokens A, which constitutes Alice's loan request.

Contract reading

Contract reading occurs when an actor reads the state or history of a contract on the ledger, or calls one of its view methods. Anyone can read a contract — whether a Hathor user or another contract. Additionally, there are three types of reading that can be performed:

• State reading
• History reading
• View method call

State reading means reading the current state of the contract — i.e., the value of the contract's attributes and its multi-token balance. History reading means reading the history of the contract — i.e., the ordered list of all NC transactions that called the contract's execution. Finally, view method call serves to obtain ad hoc information with a contract.

To better understand each of these three types of reading, let's revisit the loan contract example. A user can use the state reading endpoint of the full node API to read the value of the contract's attributes. They might do this, for instance, to check if the contract has funds of the token they want to borrow or what the standard interest rate is. They can use the history reading endpoint to find out how many times the contract has approved or rejected loan applications. Finally, they can use an endpoint to call the view method assess_credit to determine, without sending an NC transaction, the likelihood of obtaining the loan by providing their credit profile as arguments.

Actions

An action describes the transfer of tokens and authorities between the caller and the contract being created or executed during the call of a public method.

When invoking a public method, Hathor engine provides a Context object. This object contains all the information the called method needs to know about the context in which it is being called. One of the attributes of the Context object is the actions batch. Each element in the actions batch is an action the caller intends to perform on the contract, especially deposits to and withdrawals from the contract.

The actions batch may contain zero, one, or more elements. Each public method requires/accepts its own specific set(s) of actions. If the contract creation or execution succeeds, all actions are performed. Otherwise, no action is performed.

When the caller is a wallet, the call to the public method occurs via an entry point call. In this case, the set of inputs and outputs of the NC transaction is translated by Hathor protocol into the actions batch. When the caller is a contract, the contract itself provides, at runtime, the batch of actions it intends to perform along with the method arguments.

There are four types of actions:

• DEPOSIT: deposit tokens into contract.
• WITHDRAWAL: withdrawal tokens from contract.
• GRANT_AUTHORITY: grant mint/melt authority to contract.
• ACQUIRE_AUTHORITY: acquire mint/melt authority from contract.

DEPOSIT

An action of type DEPOSIT denotes a transfer of tokens from the caller’s balance to the balance of the created/executed contract. A DEPOSIT action is defined by: (i) a token UID; and (ii) an amount. It can be described by a statement in the following format: "Caller sends an amount of X token UID Y to contract".

WITHDRAWAL

An action of type WITHDRAWAL denotes a transfer of tokens from the executed contract to the caller's balance. A WITHDRAWAL action is defined by: (i) a token UID; and (ii) an amount. It can be described by a statement in the following format: "Contract sends an amount of X token UID Y to caller".

GRANT_AUTHORITY

An action of type GRANT_AUTHORITY denotes that the caller grants to the created or executed contract the authority to change the total supply of a given token. The caller can only grant this authority if they hold outputs in their balance that represent such authority — i.e., it has such authority.

An authority may allow the 'mint' operation, the 'melt' operation, or both. The mint operation issues a new amount of the token, increasing its total supply. The melt operation destroys an existing amount of the token, reducing its total supply.

The GRANT_AUTHORITY action is defined by: (i) a token UID; (ii) which operations will be allowed: mint, melt, or both. It can be described by a statement in the following format: "Caller grants mint/melt/both authority for token UID Y to the contract".

ACQUIRE_AUTHORITY

An action of type ACQUIRE_AUTHORITY denotes that the caller acquires from the executed contract an authority to change the total supply of a given token. The contract can only grant this authority if they hold it in their balance — i.e., it has such authority.

The ACQUIRE_AUTHORITY action is defined by: (i) a token UID; (ii) which operations will be allowed: mint, melt, or both. It can be described by a statement in the following format: "Caller acquires mint/melt/both authority for token UID Y from the contract".

Key takeaways

This article explained how nano contracts works dividing it into the following sections:

• In 'Architecture', we explained how the nano contracts feature works at the protocol level.
• In 'Anatomy', we presented the elements that an instance of a nano contract recorded on chain has.
• In 'Transactions', we explained the anatomy and flow of the transactions related to nano contracts.
• In 'Life cycle', we explained what happens with an instance of a contract recorded on chain once it is created.
• Finally, In 'Behavior', we explained how this life cycle takes place, by detailing actors, interactions and actions.

With this, we covered all the theory one needs to know to be capable of implementing nano contracts into a use case. Note that this theory holds the same regardless of the wallet application being used, but how to put it into practice differs for each wallet application.

What's next?

• About nano contracts: to get an overview of nano contracts.

---

Footnotes

1. Hathor adopts a nomenclature for its method types inspired by the functions nomenclature in Solidity. This way, there is similarity between the behavior of public, view, and internal methods in Hathor and their counterparts in Solidity. This is done to make nano contracts intuitive and easy for blockchain developers. However, note that there is no exact match between a method type in Hathor and the corresponding function in Solidity. Therefore, although they share the same essence, not everything that applies to a public function in Solidity applies to a public method in Hathor, and so on. ↩