.. TODO tezos/tezos#2170: search shifted protocol name/number & adapt

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
<https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-7/tzip-7.md>`_.
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 Octez client.

For a more general presentation of token standards such as FA1.2 from a Tezos developer perspective, using higher-level smart contract languages, see `Token standards in Tezos <https://docs.tezos.com/architecture/tokens#token-standards>`__.

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
<https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-7/ManagedLedger.tz>`_.
`Edukera <https://archetype-lang.org/docs/templates/fa12/>`_ and
`camlCase <https://gitlab.com/camlcase-dev/fa1.2>`_ both provide a contract that
implements the standard, and both have been verified using the `Mi-Cho-Coq
<https://gitlab.com/nomadic-labs/mi-cho-coq/>`_ framework (see related :gl:`merge
request <nomadic-labs/mi-cho-coq!97>`).

The ``octez-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
<https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-4/tzip-4.md#view-entrypoints>`_
(the ``get*`` entrypoints) offchain, without doing an explicit transaction that
returns a value on a given contract.

``octez-client man fa1.2`` gives a complete list of the :ref:`built-in commands
<client_manual>` 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
``octez-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.

- ``octez-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).
- ``octez-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 tez, ``octez-client`` supports batch transfer of tokens from a single
source to multiple recipients on multiple FA1.2 contracts, using the command
``octez-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:

.. code-block:: javascript

   [{ "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 tez 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 ``octez-codec describe
<protocol_name>.fa1.2.token_transfer json schema`` (where ``<protocol_name>``
can be replaced with e.g. ``alpha`` or ``018-Proxford``).


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
<https://gitlab.com/tezos/tzip/-/blob/master/proposals/tzip-4/tzip-4.md#view-entrypoints>`_:
they give back the requested information as a transaction on a given contract,
assuming its parameter is compatible.

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