Feat/queries examples (#66)

* feat: add quick example overview in the README and the presentation * fix: missing target in documentation * feat: add queries examples as tutorials * feat: add checks and an error for query results types definitions * feat: update step definitions * docs: update changelog * Bump version: 2.1.0-dev1 → 2.1.0-dev2 --------- Co-authored-by: github-actions <[email protected]>
Catenscia · Feb 29, 2024 · 020e649 · 020e649
1 parent cba35e7
commit 020e649
Show file tree

Hide file tree

Showing 25 changed files with 1,892 additions and 71 deletions.
diff --git a/README.md b/README.md
@@ -8,7 +8,12 @@ MxOps aims to be useful in these situations:
 - on-chain integration tests
 - contract interaction automation
 
-For a quick overview, here's how to create a token, assign a mint role and mint tokens with MxOps:
+
+## Quick Overview
+
+Here are some basic uses cases to illustrate how MxOps works.
+
+### Token Mint
 
 ```yaml
 allowed_networks:
@@ -18,37 +23,145 @@ allowed_networks:
 allowed_scenario:
   - "alice_mint"
 
-accounts:
+accounts:  # define the accounts to use
   - account_name: alice
     pem_path: ./wallets/alice.pem
 
 steps:
-  - type: FungibleIssue
+  - type: FungibleIssue  # Issue the fungible token
     sender: alice
     token_name: AliceToken
     token_ticker: ATK
     initial_supply: 1000000000  # 1,000,000.000 ATK
     num_decimals: 3
     can_add_special_roles: true
 
-  - type: ManageFungibleTokenRoles
+  - type: ManageFungibleTokenRoles  # assign mint and burn roles to alice
     sender: alice
-    is_set: true    # if we want to set or unset the roles below
+    is_set: true
     token_identifier: "%AliceToken.identifier"
     target: alice
     roles:
       - ESDTRoleLocalMint
       - ESDTRoleLocalBurn
 
-  - type: FungibleMint
+  - type: FungibleMint  # make alice mint some tokens
     sender: alice
     token_identifier: "%AliceToken.identifier"
     amount: 100000000  # 100,000.000 ATK
 
 ```
 
+### Query with ABI
+
+```yaml
+allowed_networks:
+    - mainnet
+
+allowed_scenario:
+    - .*
+
+external_contracts:
+  onedex-swap: 
+    address: erd1qqqqqqqqqqqqqpgqqz6vp9y50ep867vnr296mqf3dduh6guvmvlsu3sujc
+    abi_path: ./abis/onedex-sc.abi.json
+
+steps:
+
+  - type: ContractQuery
+    contract: onedex-swap
+    endpoint: viewPair
+    arguments:
+      - 10  # id of the pair to get the details of
+    print_results: true
+```
+
+```bash
+[
+    {
+        "pair_id": 10,
+        "state": {
+            "name": "Active",
+            "discriminant": 1,
+            "values": null
+        },
+        "enabled": true,
+        "owner": "erd1rfs4pg224d2wmndmntvu2dhfhesmuda6m502vt5mfctn3wg7tu4sk6rtku",
+        "first_token_id": "MPH-f8ea2b",
+        "second_token_id": "USDC-c76f1f",
+        "lp_token_id": "MPHUSDC-777138",
+        "lp_token_decimal": 18,
+        "first_token_reserve": 16,
+        "second_token_reserve": 1076937,
+        "lp_token_supply": 393944771203191982,
+        "lp_token_roles_are_set": true
+    }
+]
+```
+
+### Query without ABI
+
+```yaml
+allowed_networks:
+    - mainnet
+
+allowed_scenario:
+    - .*
+
+external_contracts:
+  xexchange-wegld-usdc: erd1qqqqqqqqqqqqqpgqeel2kumf0r8ffyhth7pqdujjat9nx0862jpsg2pqaq
+
+steps:
+
+  - type: ContractQuery
+    contract: xexchange-wegld-usdc
+    endpoint: getReservesAndTotalSupply
+    print_results: true
+    results_types:
+      - type: BigUint
+      - type: BigUint
+      - type: BigUint
+```
+
+```bash
+[
+    81478482319716395147753,
+    4878990096191,
+    9390873908175
+]
+```
+
+### Contract Call with Payments
+
+```yaml
+allowed_networks:
+  - localnet
+  - testnet
+  - devnet
+
+allowed_scenario:
+  - .*
+
+steps:
+  - type: ContractCall
+    sender: thomas
+    contract: pair-contract
+    endpoint: addLiquidity
+    arguments:
+      - 984849849765987  # (min amount out for slippage protection)
+    esdt_transfers:
+      - token_identifier: TOKENA-abcdef
+        amount: 894916519846515
+        nonce: 0
+      - token_identifier: TOKENB-abcdef
+        amount: 710549841216484
+        nonce: 0
+    gas_limit: 12000000
+```
+
 ## Getting Started
 
+You have seen above some basic use-cases but MxOps has much more avaible features!
 Heads up to the [documentation](https://mxops.readthedocs.io) to get started! You will find tutorials, user documentation and examples 🚀
 
 ## Contribution

diff --git a/docs/dictionary/custom_wordlist.txt b/docs/dictionary/custom_wordlist.txt
@@ -7,17 +7,21 @@ backend
 blockchain
 blockchains
 abcdef
+catenscia
+Catenscia
 ChangeLog
 config
 configparser
 cli
 customization
 customizations
+decrypt
 DevOps
 env
 environ
 Etienne
 enum
+gg
 isize
 json
 https
@@ -39,6 +43,8 @@ reusability
 SBTS
 sdk
 sdks
+StackOverflow
+stackoverflow
 td
 th
 VScode

diff --git a/docs/dictionary/multiversx_wordlist.txt b/docs/dictionary/multiversx_wordlist.txt
@@ -27,6 +27,7 @@ MultiValue
 MultiValueEncoded
 multiversx
 MultiversX
+MultiversXDevelopers
 mxpy
 mx
 NestedDecode

diff --git a/docs/source/dev_documentation/changelog.md b/docs/source/dev_documentation/changelog.md
@@ -5,6 +5,7 @@
 ## Added
 
 - ABI support for smart-contract
+- Added new examples for queries
 
 ## 2.0.1 - 2023-10-25
 

diff --git a/docs/source/examples/piggy_bank.md b/docs/source/examples/piggy_bank.md
@@ -188,6 +188,7 @@ We will give the deployed contract the id "abc-esdt-minter". (ABC will be the na
 type: ContractDeploy
 sender: owner
 wasm_path: "./contracts/esdt-minter/output/esdt-minter.wasm"
+abi_path: "./contracts/esdt-minter/output/esdt-minter.abi.json"
 contract_id: "abc-esdt-minter"
 gas_limit: 50000000
 arguments:
@@ -218,18 +219,17 @@ arguments:
 
 ##### Token Identifier
 
-We want to retrieve the token identifier that has been assigned to the newly issued token. For that we can use a query to access the view on the ESDTmapper from the contract.
+We want to retrieve the token identifier that has been assigned to the newly issued token. For that we can execute a query to access the view on the ESDTmapper from the contract.
 We will save this identifier as a string under the name `EsdtIdentifier`.
 
 ```yaml
 type: ContractQuery
 contract: "abc-esdt-minter"
 endpoint: getEsdtIdentifier
 arguments: []
-expected_results:
-    - save_key: EsdtIdentifier
-    result_type: str
 print_results: true
+results_save_keys:
+  - EsdtIdentifier
 ```
 
 ##### Results
@@ -249,6 +249,7 @@ steps:
   - type: ContractDeploy
     sender: owner
     wasm_path: "./contracts/esdt-minter/output/esdt-minter.wasm"
+    wasm_path: "./contracts/esdt-minter/output/esdt-minter.abi.json"
     contract_id: "abc-esdt-minter"
     gas_limit: 50000000
     arguments:
@@ -273,10 +274,9 @@ steps:
     contract: "abc-esdt-minter"
     endpoint: getEsdtIdentifier
     arguments: []
-    expected_results:
-      - save_key: EsdtIdentifier
-        result_type: str
     print_results: true
+    results_save_keys:
+      - EsdtIdentifier
 ```
 
 #### PiggyBank Initialization
@@ -296,6 +296,7 @@ As we also save the token identifier, we can access it too: `%abc-esdt-minter.Es
 type: ContractDeploy
 sender: owner
 wasm_path: "./contracts/piggy-bank/output/piggy-bank.wasm"
+wasm_path: "./contracts/piggy-bank/output/piggy-bank.abi.json"
 contract_id: "abc-piggy-bank"
 gas_limit: 80000000
 arguments:
@@ -338,6 +339,7 @@ steps:
   - type: ContractDeploy
     sender: owner
     wasm_path: "./contracts/piggy-bank/output/piggy-bank.wasm"
+    wasm_path: "./contracts/piggy-bank/output/piggy-bank.abi.json"
     contract_id: "abc-piggy-bank"
     gas_limit: 80000000
     arguments: