Documentation: Solang Aqd (hyperledger-solang#1588)

Adds documentation for [Solang Aqd](https://github.com/hyperledger/solang-aqd),
a CLI tool for working with Solana and Polkadot smart contracts.

Signed-off-by: Tarek <[email protected]>
Co-authored-by: Cyrill Leutwiler <[email protected]>

Author: tareknaser

README.md

@@ -60,15 +60,15 @@ Here is a brief description of what we envision for the next versions.
 
 ### V0.4
 
-| Feature                                            | Status      |
-|----------------------------------------------------|-------------|
-| Improve management over optimization passes        | Not started |
-| Adopt single static assignment for code generation | In progress |
-| Support openzeppelin on Polkadot target            | In progress |
-| Provide Solidity -> Polkadot porting guide         | Not started |
-| Declare accounts for a Solidity function on Solana | In progress |
-| Tooling for calls between ink! <> solidity         | In progress |
-| Provide CLI for node interactions                  | In progress |
+| Feature                                            | Status                                               |
+|----------------------------------------------------|------------------------------------------------------|
+| Improve management over optimization passes        | Not started                                          |
+| Adopt single static assignment for code generation | In progress                                          |
+| Support openzeppelin on Polkadot target            | In progress                                          |
+| Provide Solidity -> Polkadot porting guide         | Not started                                          |
+| Declare accounts for a Solidity function on Solana | In progress                                          |
+| Tooling for calls between ink! <> solidity         | In progress                                          |
+| Provide CLI for node interactions                  | [Done](https://github.com/hyperledger/solang-aqd)    |
 
 ## License
 

docs/aqd.rst

@@ -0,0 +1,307 @@
+Interacting with smart contracts on the command line
+====================================================
+Solang Aqd (عَقد, meaning "contract" in Arabic), is a Command-Line Interface (CLI) tool 
+designed for easy interaction with smart contracts on Solana and Polkadot blockchains.
+It simplifies the process of deploying smart contracts and executing specific functions on these contracts.
+
+Solang Aqd distinguishes itself by offering seamless integration with Solang-compiled contracts and is actively maintained by the Solang team. 
+When it comes to Polkadot, Solang Aqd focuses specifically on essential commands for node interactions with on-chain contracts. 
+In the case of Solana, Solang Aqd fills a notable gap as there currently isn't a dedicated tool for calling specific functions on deployed Solana contracts.
+
+
+Installation
+____________
+
+As of now, the only available method to install ``solang-aqd`` is via Cargo. Run the following command:
+
+.. code-block:: bash
+
+    cargo install --force --locked aqd
+    
+To update to the latest version, use the same command.
+
+
+.. note::
+
+    If you're interested in a specific target, you can use feature flags. For example, to install with only the Solana target, use:
+
+    .. code-block:: bash
+
+        cargo install --force --locked aqd --no-default-features --features solana
+
+
+Submitting extrinsics to Polkadot on-chain
+__________________________________________
+
+The command line syntax for interacting with a program deployed on Polkadot is as follows:
+
+aqd polkadot [SUBCOMMAND] [OPTIONS]... [FILE]
+
+The command line is ``aqd polkadot`` followed by a subcommand followed by any options described below,
+followed by the filename. The filename could be ``.wasm file``, ``.contract`` bundle, or ``.json`` metadata file.
+
+.. note::
+  Under the hood, Solang Aqd utilizes ``cargo-contract`` for submitting extrinsics to Polkadot on-chain. 
+  For detailed documentation of specific parameters, please refer to 
+  `contract extrinsics documentation <https://github.com/paritytech/cargo-contract/blob/master/crates/extrinsics/README.md>`_.
+
+General Options (for all subcommands):
+++++++++++++++++++++++++++++++++++++++
+
+\-\-url *url*
+  The websockets URL for the substrate node. [default: ws://localhost:9944]
+
+\-\-network *network*
+  Specify the network name to use.
+  You can either specify a network name or a URL, but not both.
+
+  Network:
+
+  rococo
+    Contracts (Rococo) (Equivalent to ``--url wss://rococo-contracts-rpc.polkadot.io``)
+
+  phala-po-c5
+    Phala PoC-5 (Equivalent to ``--url wss://poc5.phala.network/ws``)
+
+  astar-shiden
+    Astar Shiden (Kusama) (Equivalent to ``--url wss://rpc.shiden.astar.network``)
+
+  astar-shibuya
+    Astar Shibuya (Tokio) (Equivalent to ``--url wss://rpc.shibuya.astar.network``)
+
+  astar
+    Astar (Equivalent to ``--url wss://rpc.astar.network``)
+
+  aleph-zero-testnet
+    Aleph Zero Testnet (Equivalent to ``--url wss://ws.test.azero.dev``)
+
+  aleph-zero
+    Aleph Zero (Equivalent to ``--url wss://ws.azero.dev``)
+  
+  t3rnt0rn
+    T3RN T0RN (Equivalent to ``--url wss://ws.t0rn.io``)
+  
+  pendulum-testnet
+    Pendulum Testnet (Equivalent to ``--url wss://rpc-foucoco.pendulumchain.tech``)
+
+-s, \-\-suri *suri*
+  Specifies the secret key URI used for deploying the contract (must be specified). For example:
+    For a development account: ``//Alice``
+    
+    With a password: ``//Alice///SECRET_PASSWORD``
+
+-x, \-\-execute
+  Specifies whether to submit the extrinsic for on-chain execution; if not provided, it will perform a dry run and return the result.
+
+\-\-storage-deposit-limit *storage-deposit-limit*
+  Specifies the maximum amount of balance that can be charged from the caller to pay for the storage consumed.
+
+\-\-output-json
+  Specifies whether to export the call output in JSON format.
+
+\-\-help, -h
+  This displays a short description of all the options
+
+Subcommands:
+++++++++++++
+
+Upload Subcommand
+-----------------
+
+This subcommand enables the uploading of contracts onto the Polkadot blockchain.
+
+.. code-block:: bash
+
+  aqd polkadot upload --suri //Alice -x flipper.contract --output-json
+
+Instantiate Subcommand
+----------------------
+
+This subcommand facilitates the instantiation of contracts on the Polkadot blockchain.
+
+.. code-block:: bash
+
+  aqd polkadot instantiate --suri //Alice --args true -x --output-json --skip-confirm flipper.contract
+
+Options specific to the ``instantiate`` subcommand:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\-\-constructor *constructor*
+  Specifies the name of the contract constructor to call. [default: new]
+
+\-\-args *<args>...*
+  Accepts a space separated list of values, encoded in order as the arguments of the constructor to invoke.
+
+\-\-value *value*
+  Specifies the value to be transferred as part of the call. [default: 0]
+
+\-\-gas *gas*
+  Specifies the maximum amount of gas to be used for this command.
+
+\-\-proof-size *proof-size*
+  Specifies the maximum proof size for this instantiation.
+
+\-\-salt *salt*
+  Specifies a salt used in the address derivation of the new contract.
+
+-y, \-\-skip-confirm
+  When set, skips the interactive confirmation prompt.
+
+Call Subcommand
+---------------
+
+This subcommand enables the calling of contracts on the Polkadot blockchain.
+
+.. code-block:: bash
+
+  aqd polkadot call --contract 5EFYe3hkH2wFK1mLxD5VSqD88hfPZWihXAKeqozZELsL4Ueq --message get --suri //Alice flipper.contract --output-json --skip-confirm
+
+Options specific to the ``call`` subcommand:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\-\-contract *contract*
+  Specifies the address of the contract to call.
+
+-m, \-\-message *message*
+  Specifies the name of the contract message to call.
+
+\-\-args *<args>...*
+  Accepts a space separated list of values, encoded in order as the arguments of the message to invoke.
+
+\-\-value *value*
+  Specifies the value to be transferred as part of the call. [default: 0]
+
+\-\-gas *gas*
+  Specifies the maximum amount of gas to be used for this command.
+
+\-\-proof-size *proof-size*
+  Specifies the maximum proof size for this call.
+
+-y, \-\-skip-confirm
+  When set, skips the interactive confirmation prompt.
+
+Remove Subcommand
+-----------------
+
+This subcommand allows for the removal of contracts from the Polkadot blockchain.
+
+.. code-block:: bash
+
+  aqd polkadot remove --suri //Alice --output-json --code-hash 0x94e67200d3d8f0f420873f8d1b426fdf5eb87f208c6e5d061822e017ffaef2a8 flipper.contract
+
+Options specific to the ``remove`` subcommand:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\-\-code-hash *code_hash*
+  Specifies the code hash to remove.
+
+
+Interacting with Solana running programs on-chain
+_________________________________________________
+
+The command line syntax for interacting with a program deployed on Solana is as follows:
+
+  aqd solana [SUBCOMMAND] [OPTIONS]...
+
+It consists of a subcommand followed by its options, both of which are described below. 
+
+.. note::
+
+  Solang Aqd relies on the local default Solana configuration file to obtain information for transaction submissions. 
+  For comprehensive management of this configuration file, you can refer to `Solana's CLI command documentation <https://docs.solana.com/cli/usage#solana-config>`_.
+
+General Options (for all subcommands):
+++++++++++++++++++++++++++++++++++++++
+
+\-\-output-json
+  Specifies whether to export the call output in JSON format.
+
+\-\-help, -h
+  This displays a short description of all the options.
+
+Subcommands:
+++++++++++++
+
+Deploy Subcommand
+------------------
+
+Allows you to deploy Solana compiled programs to Solana.
+
+.. code-block:: bash
+
+  aqd solana deploy flipper.so
+
+
+Show Subcommand
+---------------
+
+Show information about a Solana program's instructions given an IDL JSON file.
+
+.. code-block:: bash
+
+  aqd solana show --idl flipper.json --instruction new 
+
+Options specific to the ``show`` subcommand:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\-\-idl *idl-json-file-path*
+  Specifies the path of the IDL JSON file.
+
+\-\-instruction *instruction-name*
+  Specifies the name of the instruction to show information about.
+  If not specified, information about all instructions is shown.
+
+Call Subcommand
+---------------
+
+Allows you to send a custom transaction to a Solana program, enabling the execution of specific functions within the deployed smart contract.
+
+.. code-block:: bash
+
+  aqd solana call --idl flipper.json --program G2eBnLvwPCGCFVywrUT2LtKCCYFkGetAVXJfW82UXmPe --instruction new --data true --accounts new self system
+
+To interact with a function on a Solana-deployed smart contract, you'll need to specify key details like the program's address, data arguments, necessary accounts, and signatories. 
+Solang Aqd simplifies this process by accepting these parameters as command-line arguments. 
+Additionally, it ensures the submitted transaction aligns with the expected values in the Interface Description Language (IDL).
+
+.. note::
+  If unsure, you can always check the expected arguements and accounts for a specific function by using the ``show`` subcommand.
+
+Options specific to the ``call`` subcommand:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+\-\-idl *idl-json-file-path*
+  Specifies the path of the IDL JSON file.
+
+\-\-program *program*
+  Specifies the program ID of the deployed program.
+
+\-\-instruction *instruction-name*
+  Specifies the name of the instruction to show information about.
+  If not specified, information about all instructions is shown.
+
+\-\-program *program*
+  Specifies the program ID of the deployed program.
+
+\-\-data *<data-arguments>...*
+  Specifies the data arguments to pass to the instruction.
+  For arrays and vectors, pass a comma-separated list of values. (e.g. 1,2,3,4).
+  For structs, pass a JSON string of the struct. (can be a path to a JSON file).
+
+\-\-accounts *<account-arguments>...*
+  Specifies the accounts arguments to pass to the instruction
+
+  Keywords:
+
+  new
+    Creates a new solana account and saves it locally. 
+
+  self
+    Reads the default keypair from the local configuration file.
+
+  system
+    Uses the system program ID as the account.
+
+\-\-payer *payer*
+  Specifies the payer keypair to use for the transaction. [default: local default keypair]
+  

docs/index.rst

@@ -31,6 +31,7 @@ Contents
 
    installing
    running
+   aqd
    extension
    examples