From bedca6a6d2b0bf6d287a1623d110f123fa89369a Mon Sep 17 00:00:00 2001 From: Tarek Date: Sat, 4 Nov 2023 21:26:02 +0200 Subject: [PATCH 1/3] docs: add documentation for Solang Aqd - Added detailed documentation for Solang Aqd, a CLI tool for interacting with smart contracts on Solana and Polkadot blockchains. - Included instructions for installation, submitting extrinsics to the Polkadot on-chain, and interacting with Solana running programs on-chain. Signed-off-by: Tarek --- docs/aqd.rst | 283 +++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 2 files changed, 284 insertions(+) create mode 100644 docs/aqd.rst diff --git a/docs/aqd.rst b/docs/aqd.rst new file mode 100644 index 000000000..d19e1b5ec --- /dev/null +++ b/docs/aqd.rst @@ -0,0 +1,283 @@ +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. +This documentation provides essential guidance for using ``solang-aqd`` effectively. + + +Installation +____________ + +To install `solang-aqd`, run this command: + +.. code-block:: bash + + cargo install --force --locked aqd + +To update to the latest version, use the same command. + + +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] + +This means that 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. + +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. + +\-\-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 *...* + Specifies the arguments of the contract constructor to call. + +\-\-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 *...* + Specifies the arguments of the contract message to call. + +\-\-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 `_. + +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 +--------------- + +Send a custom transaction to a Solana program. + +.. code-block:: bash + + aqd solana call --idl flipper.json --program G2eBnLvwPCGCFVywrUT2LtKCCYFkGetAVXJfW82UXmPe --instruction new --data true --accounts new self system + +Options specific to the ``show`` 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 *...* + 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 *...* + 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] + \ No newline at end of file diff --git a/docs/index.rst b/docs/index.rst index b77502d58..bc5920dd6 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,6 +31,7 @@ Contents installing running + aqd extension examples From 6427ecb05fc69f4889ca430e903956328b3db8ac Mon Sep 17 00:00:00 2001 From: Tarek Date: Sat, 11 Nov 2023 17:50:36 +0200 Subject: [PATCH 2/3] docs: mark CLI for node interactions as Done Signed-off-by: Tarek --- README.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 209b0c595..f3b1094bb 100644 --- a/README.md +++ b/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 From 88fd2631085cfd732f74f25f5128a6c119426878 Mon Sep 17 00:00:00 2001 From: Tarek Date: Thu, 16 Nov 2023 03:24:55 +0200 Subject: [PATCH 3/3] docs: make aqd docs more verbose Signed-off-by: Tarek --- docs/aqd.rst | 44 ++++++++++++++++++++++++++++++++++---------- 1 file changed, 34 insertions(+), 10 deletions(-) diff --git a/docs/aqd.rst b/docs/aqd.rst index d19e1b5ec..071390fa0 100644 --- a/docs/aqd.rst +++ b/docs/aqd.rst @@ -2,14 +2,17 @@ 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. -This documentation provides essential guidance for using ``solang-aqd`` effectively. +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 ____________ -To install `solang-aqd`, run this command: +As of now, the only available method to install ``solang-aqd`` is via Cargo. Run the following command: .. code-block:: bash @@ -18,6 +21,15 @@ To install `solang-aqd`, run this command: 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 __________________________________________ @@ -25,9 +37,14 @@ The command line syntax for interacting with a program deployed on Polkadot is a aqd polkadot [SUBCOMMAND] [OPTIONS]... [FILE] -This means that the command line is ``aqd polkadot`` followed by a subcommand followed by any options described below, +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 `_. + General Options (for all subcommands): ++++++++++++++++++++++++++++++++++++++ @@ -74,7 +91,7 @@ General Options (for all subcommands): With a password: ``//Alice///SECRET_PASSWORD`` -x, \-\-execute - Specifies whether to submit the extrinsic for on-chain execution. + 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. @@ -113,7 +130,7 @@ Options specific to the ``instantiate`` subcommand: Specifies the name of the contract constructor to call. [default: new] \-\-args *...* - Specifies the arguments of the contract constructor to call. + 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] @@ -133,7 +150,7 @@ Options specific to the ``instantiate`` subcommand: Call Subcommand --------------- -This subcommand enables the calling of contracts on the Polkadot blockchain." +This subcommand enables the calling of contracts on the Polkadot blockchain. .. code-block:: bash @@ -149,7 +166,7 @@ Options specific to the ``call`` subcommand: Specifies the name of the contract message to call. \-\-args *...* - Specifies the arguments of the contract message to call. + 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] @@ -237,13 +254,20 @@ Options specific to the ``show`` subcommand: Call Subcommand --------------- -Send a custom transaction to a Solana program. +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 -Options specific to the ``show`` subcommand: +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*