.. 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 `_. 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 `__. 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 :gl:`merge request `). 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 `_ (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 ` 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 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 transfer from to `` transfers a given ``amount`` of tokens from ``sender`` to ``receiver``. In that case ``sender`` is the caller of the contract. If ``--as `` 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 approve as from `` 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 using ``. 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 ``, 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": , // address or alias of the FA1.2 contract "destination": , // address or alias of the recipient of the transfer "amount": , // amount of tokens to transfer as a string "tez_amount": , // (optional) amount of tez to send with transaction as a string "fee": , // (optional) custom fees for the transaction as a string "gas_limit": , // (optional) gas limit for the transaction as a string "storage_limit": , // (optional) storage limit the transaction can use as a string }, .. ] The complete schema can be inspected via ``octez-codec describe .fa1.2.token_transfer json schema`` (where ```` 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 `_: 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 get balance for ``, or the allowance using ``octez-client from fa1.2 contract get allowance on as ``.