Add spl-token integration

docs/index.rst

@@ -25,9 +25,16 @@ Contents
    installing
    running
    extension
-   targets
    examples
 
+.. toctree::
+   :maxdepth: 3
+   :caption: Targets
+
+   targets/solana.rst
+   targets/substrate.rst
+   targets/burrow.rst
+
 .. toctree::
    :maxdepth: 3
    :caption: Solidity language

docs/language/imports.rst

@@ -72,79 +72,3 @@ This also has a slightly more baroque syntax, which does exactly the same.
 .. code-block:: solidity
 
     import * as defs from "defines.sol";
-
-Builtin Imports
-_______________
-
-Some builtin functionality is only available after importing. The following structs
-can be imported via the special import file ``solana``.
-
-.. code-block:: solidity
-
-    import {AccountMeta, AccountInfo} from 'solana';
-
-Note that ``{AccountMeta, AccountInfo}`` can be omitted, renamed or imported via
-import object.
-
-.. code-block:: solidity
-
-    // Now AccountMeta will be known as AM
-    import {AccountMeta as AM} from 'solana';
-
-    // Now AccountMeta will be available as solana.AccountMeta
-    import 'solana' as solana;
-
-.. note::
-
-    The import file ``solana`` is only available when compiling for the Solana
-    target.
-
-.. _account_info:
-
-Builtin AccountInfo
-+++++++++++++++++++
-
-The account info of all the accounts passed into the transaction. ``AccountInfo`` is a builtin
-structure with the following fields:
-
-address ``key``
-    The address (or public key) of the account
-
-uint64 ``lamports``
-    The lamports of the accounts. This field can be modified, however the lamports need to be
-    balanced for all accounts by the end of the transaction.
-
-bytes ``data```
-    The account data. This field can be modified, but use with caution.
-
-address ``owner``
-    The program that owns this account
-
-uint64 ``rent_epoch``
-    The next epoch when rent is due.
-
-bool ``is_signer``
-    Did this account sign the transaction
-
-bool ``is_writable``
-    Is this account writable in this transaction
-
-bool ``executable``
-    Is this account a program
-
-.. _account_meta:
-
-Builtin AccountMeta
-+++++++++++++++++++
-
-When doing an external call (aka CPI), ``AccountMeta`` specifies which accounts
-should be passed to the callee.
-
-address ``pubkey``
-    The address (or public key) of the account
-
-bool ``is_writable``
-    Can the callee write to this account
-
-bool ``is_signer``
-    Can the callee assume this account signed the transaction

docs/targets/burrow.rst

@@ -0,0 +1,18 @@
+Hyperledger Burrow (ewasm)
+==========================
+
+The ewasm specification is not finalized yet. There is no `create2` or `chainid` call, and the keccak256 precompile
+contract has not been finalized yet.
+
+In Burrow, Solang is used transparently by the ``burrow deploy`` tool if it is given the ``--wasm`` argument.
+When building and deploying a Solidity contract, rather than running the ``solc`` compiler, it will run
+the ``solang`` compiler and deploy it as a wasm contract.
+
+This is documented in the `burrow documentation <https://hyperledger.github.io/burrow/#/reference/wasm>`_.
+
+ewasm has been tested with `Hyperledger Burrow <https://github.com/hyperledger/burrow>`_.
+Please use the latest master version of burrow, as ewasm support is still maturing in Burrow.
+
+Some language features have not been fully implemented yet on ewasm:
+
+- Contract storage variables types ``string``, ``bytes`` and function types are not implemented

docs/targets.rst → docs/targets/solana.rst

@@ -1,8 +1,5 @@
-Targets
-=======
-
 Solana
-______
+======
 
 The Solana target requires `Solana <https://www.solana.com/>`_ v1.8.1.
 
@@ -76,49 +73,95 @@ package has `documentation <https://solana-labs.github.io/solana-solidity.js/>`_
 are `some examples <https://solana-labs.github.io/solana-solidity.js/>`_. There is also
 `solang's integration tests <https://github.com/hyperledger-labs/solang/tree/main/integration/solana>`_.
 
-Parity Substrate
+
+Builtin Imports
 ________________
 
-Solang works with Parity Substrate 2.0 or later.
+Some builtin functionality is only available after importing. The following structs
+can be imported via the special import file ``solana``.
 
-The Parity Substrate has the following differences to Ethereum Solidity:
+.. code-block:: solidity
 
-- The address type is 32 bytes, not 20 bytes. This is what Substrate calls an "account"
-- An address literal has to be specified using the ``address"5GBWmgdFAMqm8ZgAHGobqDqX6tjLxJhv53ygjNtaaAn3sjeZ"`` syntax
-- ABI encoding and decoding is done using the `SCALE <https://substrate.dev/docs/en/knowledgebase/advanced/codec>`_ encoding
-- Multiple constructors are allowed, and can be overloaded
-- There is no ``ecrecover()`` builtin function, or any other function to recover or verify cryptographic signatures at runtime
-- Only functions called via rpc may return values; when calling a function in a transaction, the return values cannot be accessed
-- An `assert()`, `require()`, or `revert()` executes the wasm unreachable instruction. The reason code is lost
+    import {AccountMeta, AccountInfo} from 'solana';
 
-There is an solidity example which can be found in the
-`examples <https://github.com/hyperledger-labs/solang/tree/main/examples>`_
-directory. Write this to flipper.sol and run:
+Note that ``{AccountMeta, AccountInfo}`` can be omitted, renamed or imported via
+import object.
 
-.. code-block:: bash
+.. code-block:: solidity
+
+    // Now AccountMeta will be known as AM
+    import {AccountMeta as AM} from 'solana';
+
+    // Now AccountMeta will be available as solana.AccountMeta
+    import 'solana' as solana;
+
+.. note::
+
+    The import file ``solana`` is only available when compiling for the Solana
+    target.
+
+.. _account_info:
+
+Builtin AccountInfo
++++++++++++++++++++
+
+The account info of all the accounts passed into the transaction. ``AccountInfo`` is a builtin
+structure with the following fields:
+
+address ``key``
+    The address (or public key) of the account
+
+uint64 ``lamports``
+    The lamports of the accounts. This field can be modified, however the lamports need to be
+    balanced for all accounts by the end of the transaction.
+
+bytes ``data```
+    The account data. This field can be modified, but use with caution.
+
+address ``owner``
+    The program that owns this account
+
+uint64 ``rent_epoch``
+    The next epoch when rent is due.
+
+bool ``is_signer``
+    Did this account sign the transaction
+
+bool ``is_writable``
+    Is this account writable in this transaction
 
-  solang --target substrate flipper.sol
+bool ``executable``
+    Is this account a program
 
-Now you should have a file called ``flipper.contract``. The file contains both the ABI and contract wasm.
-It can be used directly in the
-`Polkadot UI <https://substrate.dev/substrate-contracts-workshop/#/0/deploy-contract>`_, as if the contract was written in ink!.
+.. _account_meta:
 
+Builtin AccountMeta
++++++++++++++++++++
 
-Hyperledger Burrow (ewasm)
-__________________________
+When doing an external call (aka CPI), ``AccountMeta`` specifies which accounts
+should be passed to the callee.
 
-The ewasm specification is not finalized yet. There is no `create2` or `chainid` call, and the keccak256 precompile
-contract has not been finalized yet.
+address ``pubkey``
+    The address (or public key) of the account
 
-In Burrow, Solang is used transparently by the ``burrow deploy`` tool if it is given the ``--wasm`` argument.
-When building and deploying a Solidity contract, rather than running the ``solc`` compiler, it will run
-the ``solang`` compiler and deploy it as a wasm contract.
+bool ``is_writable``
+    Can the callee write to this account
 
-This is documented in the `burrow documentation <https://hyperledger.github.io/burrow/#/reference/wasm>`_.
+bool ``is_signer``
+    Can the callee assume this account signed the transaction
 
-ewasm has been tested with `Hyperledger Burrow <https://github.com/hyperledger/burrow>`_.
-Please use the latest master version of burrow, as ewasm support is still maturing in Burrow.
+Using spl-token
+_______________
 
-Some language features have not been fully implemented yet on ewasm:
+`spl-token <https://spl.solana.com/token>`_ is the solana native way of creating tokens, minting, burning and
+transfering token. This is the Solana equivalent of
+`ERC-20 <https://ethereum.org/en/developers/docs/standards/tokens/erc-20/>`_ and
+`ERC-721 <https://ethereum.org/en/developers/docs/standards/tokens/erc-721/>`_. We have created a library ``SplToken`` to use
+spl-token from Solidity. The file
+`spl_token.sol <https://github.com/hyperledger-labs/solang/blob/main/examples/spl_token.sol>`_  should be copied into
+your source tree, and then imported in your solidity files where it is required. The ``SplToken`` library has doc
+comments explaining how it should be used.
 
-- Contract storage variables types ``string``, ``bytes`` and function types are not implemented
+There is an example in our integration tests of how this should be used, see
+`token.sol <https://github.com/hyperledger-labs/solang/blob/main/integration/solana/token.sol>`_ and
+`token.spec.ts <https://github.com/hyperledger-labs/solang/blob/main/integration/solana/token.spec.ts>`_.

docs/targets/substrate.rst

@@ -0,0 +1,26 @@
+Parity Substrate
+================
+
+Solang works with Parity Substrate 2.0 or later.
+
+The Parity Substrate has the following differences to Ethereum Solidity:
+
+- The address type is 32 bytes, not 20 bytes. This is what Substrate calls an "account"
+- An address literal has to be specified using the ``address"5GBWmgdFAMqm8ZgAHGobqDqX6tjLxJhv53ygjNtaaAn3sjeZ"`` syntax
+- ABI encoding and decoding is done using the `SCALE <https://substrate.dev/docs/en/knowledgebase/advanced/codec>`_ encoding
+- Multiple constructors are allowed, and can be overloaded
+- There is no ``ecrecover()`` builtin function, or any other function to recover or verify cryptographic signatures at runtime
+- Only functions called via rpc may return values; when calling a function in a transaction, the return values cannot be accessed
+- An `assert()`, `require()`, or `revert()` executes the wasm unreachable instruction. The reason code is lost
+
+There is an solidity example which can be found in the
+`examples <https://github.com/hyperledger-labs/solang/tree/main/examples>`_
+directory. Write this to flipper.sol and run:
+
+.. code-block:: bash
+
+  solang --target substrate flipper.sol
+
+Now you should have a file called ``flipper.contract``. The file contains both the ABI and contract wasm.
+It can be used directly in the
+`Polkadot UI <https://substrate.dev/substrate-contracts-workshop/#/0/deploy-contract>`_, as if the contract was written in ink!.