FA1.2 support

Financial application 1.2, or FA1.2 for short, is a standard that describes the interface of smart contracts that implement ledger with balances that is described by tzip-007. We refer hereafter to FA1.2 assets by their common name: tokens.

This page does not present FA1.2 tokens in general, but their Michelson interface and their support in the Mavkit client.

For a more general presentation of token standards such as FA1.2 from a Mavryk developer perspective, using higher-level smart contract languages, see Token standards in Mavryk.

Michelson interface

An FA1.2 contract implements multiple entrypoints that describe how users can transfer tokens, approve others to withdraw tokens from their account, and retrieve some information such as balances, withdrawal allowance and total supply. The Michelson interface is then described by the following entrypoints:

  • transfer: (pair (address :from) (pair (address :to) (nat :amount)))

  • approve: (pair (address :spender) (nat :value))

  • getBalance: (pair (address :owner) (contract nat))

  • getAllowance: (pair (pair (address :owner) (address :spender)) (contract nat))

  • getTotalSupply: (pair unit (contract nat))

Multiple implementations of such a standard exist within the ecosystem. For example, one is provided with the TZIP-007 specification. Edukera and camlCase both provide a contract that implements the standard, and both have been verified using the Mi-Cho-Coq framework (see related merge request ).

The mavkit-client supports this standard with specific commands that allow the user to avoid calling FA1.2 contracts using entrypoints and forging Michelson arguments. Moreover, it supports calling views (the get* entrypoints) offchain, without doing an explicit transaction that returns a value on a given contract.

mavkit-client man fa1.2 gives a complete list of the built-in commands to interact with FA1.2-compatible contracts, with details about the syntax of each one.

Client commands

Checking whether a contract is FA1.2 compatible

To check whether a contract has an FA1.2-compatible interface, use mavkit-client check contract <alias or KT1> implements fa1.2. The underlying function is actually used before invoking any FA1.2 command.

Managing tokens

An FA1.2 contract features two main functionalities: transferring tokens from an address to another, and allowing another account to transfer an amount of tokens from its own address to any third party.

  • mavkit-client from fa1.2 contract <fa1.2> transfer <amount> from <sender> to <receiver> transfers a given amount of tokens from sender to receiver. In that case sender is the caller of the contract. If --as <operator> is given to the command, operator becomes the caller of the contract (and must have allowance on sender’s account, as explained).

  • mavkit-client from fa1.2 contract <fa1.2> approve <amount> as <sender> from <operator> allows operator to transfer a given amount of tokens from sender to any other account: this is the allowance described above.

For example, let’s assume two accounts: Alice and Bob, and a contract token tk. If Alice gives an allowance of 10 to Bob, then Bob can transfer up to 10 tokens of tk from Alice to any other account.

Batch transfer of tokens

As for mav, mavkit-client supports batch transfer of tokens from a single source to multiple recipients on multiple FA1.2 contracts, using the command mavkit-client multiple fa1.2 transfers from <account> using <json>.

To be on par with batch transactions, only one account can be the source of the transfer. However, thanks to the approval mechanism, this command takes an optional argument --as <operator>, allowing an approved account operator to make transfers from the source to any other accounts. The JSON format for the transfers is the following:

[{ "token_contract": <string>, // address or alias of the FA1.2 contract
   "destination": <string>, // address or alias of the recipient of the transfer
   "amount": <string>, // amount of tokens to transfer as a string
   "tez_amount": <string>, // (optional) amount of mav to send with transaction as a string
   "fee": <string>, // (optional) custom fees for the transaction as a string
   "gas_limit": <string>, // (optional) gas limit for the transaction as a string
   "storage_limit": <string>, // (optional) storage limit the transaction can use as a string
 },
 ..
]

The complete schema can be inspected via mavkit-codec describe <protocol_name>.fa1.2.token_transfer json schema (where <protocol_name> can be replaced with e.g. alpha or 001-PtAtLas).

View information

An FA1.2 contract implements three entrypoints that allow a user to check any account’s balance, or allowance between an account and an operator, and get the total supply of tokens of the contract. These entrypoints are implemented as offline views: they give back the requested information as a transaction on a given contract, assuming its parameter is compatible.

mavkit-client supports calling these entrypoints completely offchain. One can get a balance using mavkit-client from fa1.2 contract <contract> get balance for <account>, or the allowance using mavkit-client from fa1.2 contract <contract> get allowance on <owner> as <operator>.