Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Installing contracts: update the naming convention from deploy to transaction #1460

Closed
wants to merge 2 commits into from
Closed

Installing contracts: update the naming convention from deploy to transaction #1460

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1d1284c
update the naming convention from deploy to transaction
sczembor Jun 13, 2024
578790b
add updated put-txn commands
sczembor Jun 20, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 76 additions & 48 deletions source/docs/casper/developers/dapps/nctl-test.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@ title: Local Network Testing

# Testing Smart Contracts with NCTL

NCTL effectively simulates a live Casper network. The process for sending a `Deploy` to an NCTL-based network is therefore similar to doing so on a live network.
NCTL effectively simulates a live Casper network. The process for sending a `Transaction` to an NCTL-based network is therefore similar to doing so on a live network.

Testing `Deploys` prior to sending them to a Casper network ensures that they operate as intended. When working in an environment that requires payment for execution, errors and inefficiencies quickly add up. To this end, Casper provides several layers of testing to identify and rectify any errors. After [writing your smart contract](../../developers/writing-onchain-code/simple-contract.md) and testing it [using the provided framework](../../developers/writing-onchain-code/testing-contracts.md), NCTL serves as the next step in the process. While testing is entirely optional, it should be considered a best practice to avoid paying for the execution of faulty code.
Testing `Transactions` prior to sending them to a Casper network ensures that they operate as intended. When working in an environment that requires payment for execution, errors and inefficiencies quickly add up. To this end, Casper provides several layers of testing to identify and rectify any errors. After [writing your smart contract](../../developers/writing-onchain-code/simple-contract.md) and testing it [using the provided framework](../../developers/writing-onchain-code/testing-contracts.md), NCTL serves as the next step in the process. While testing is entirely optional, it should be considered a best practice to avoid paying for the execution of faulty code.

## Getting Started with NCTL

Prior to testing a `Deploy` through NCTL, you should have the following steps accomplished:
Prior to testing a `Transaction` that installs a smart contract through NCTL, you should have the following steps accomplished:

1) [Completed writing a Deploy](../../developers/writing-onchain-code/simple-contract.md)
1. [Completed writing a Smart Contract](../../developers/writing-onchain-code/simple-contract.md)

2) [Tested the Deploy](../../developers/writing-onchain-code/testing-contracts.md) using the Casper testing framework
2. [Tested the Smart Contract](../../developers/writing-onchain-code/testing-contracts.md) using the Casper testing framework

3) [Setup NCTL](./setup-nctl.md) on your system
3. [Setup NCTL](./setup-nctl.md) on your system

## NCTL Verification Prior to Testing

Expand All @@ -26,29 +26,39 @@ Prior to attempting an NCTL test, you must verify that your local NCTL instance
nctl-status
```

You should see five nodes `RUNNING` and five `STOPPED`. Further, verify that the node and user information propagated within the *casper-node/utils/assets* directory. Each node and user should have the associated `Keys` necessary to interact with the network. Run the following command to view first user details:
You should see five nodes `RUNNING` and five `STOPPED`. Further, verify that the node and user information propagated within the _casper-node/utils/assets_ directory. Each node and user should have the associated `Keys` necessary to interact with the network. Run the following command to view first user details:

```
nctl-view-user-account user=1
```

## Installing the Smart Contract

This document assumes that you setup your NCTL network using the standard settings in a directory called */casper/*.
This document assumes that you setup your NCTL network using the standard settings in a directory called _/casper/_.

You will need the following information to use the `put-deploy` command:
You will need the following information to use the `put-txn` command with `session` option:

* The **chain name**, in this case `casper-net-1`. This will appear in our example put-deploy as `--chain-name "casper-net-1"`
- The **chain name**, in this case `casper-net-1`. This will appear in our example put-txn as `--chain-name "casper-net-1"`

* The **secret key** of the account sending the `Deploy`. For this example, we are using node-1 as the sender. The secret key file can be found at *casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/secret_key.pem*. In our example put-deploy, this will appear as `--secret-key /casper/casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/secret_key.pem`. If your Deploy is more complex and requires multiple accounts, NCTL also establishes multiple users for testing.
- The **secret key** of the account singning the `Transaction`. For this example, we are using node-1 as the signer. The secret key file can be found at _casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/secret_key.pem_. In our example put-txn, this will appear as `--secret-key /casper/casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/secret_key.pem`. If your transaction is more complex and requires multiple accounts, NCTL also establishes multiple users for testing. You can also

* The **payment amount** in motes, which should be sufficient to avoid an 'Out of Gas' error. The payment amount will appear in our example put-deploy as `--payment-amount 2500000000`. **NCTL tests are not an accurate representation of potential gas costs on a live network. Please see our [note about gas prices](../../developers/cli/sending-transactions.md#a-note-about-gas-price).**
- The **payment amount** in motes, which should be sufficient to avoid an 'Out of Gas' error. The payment amount will appear in our example put-txn as `--payment-amount 2500000000`. **NCTL tests are not an accurate representation of potential gas costs on a live network. Please see our [note about gas prices](../../developers/cli/sending-transactions.md#a-note-about-gas-price).**

* The **path** to your `Deploy` that you wish to send to the NCTL network. This will appear in our example put-deploy as `--session-path <PATH>` and will require you to define the path to your specific `Deploy` Wasm.
- The **node address** for a node on your NCTL network. In this example, we are using the node at `http://localhost:11101`. On the Casper Mainnet or Testnet, nodes will use port `7777`. This will appear in our example put-txn as `--node-address http://<HOST>:7777`.

* The **node address** for a node on your NCTL network. In this example, we are using the node at `http://localhost:11101`. On the Casper Mainnet or Testnet, nodes will use port `7777`. This will appear in our example put-deploy as `--node-address http://<HOST>:7777`.
- The **gas-price-tolerance** the maximum gas price that the user is willing to pay for the transaction.

The command to send your `Deploy` should look similar to the following code snippet:
- The **pricing-mode** used to identify the payment mode chosen to execute the transaction.

- The **session-entry-point** name of the method that will be used when calling the session contract.

- The **standard-payment** flag to determine if this transaction uses standard or custom payment.

- The **category** transaction category [possible values: install-upgrade, large, medium, small].

- The **transaction-path** to your `Contract` WASM file that you wish to send to the NCTL network.

The command to send your `Transaction` should look similar to the following code snippet:

:::note

Expand All @@ -57,76 +67,94 @@ Use of the `$(get_path_to_client)` command assumes that you are operating in an
:::

```
$(get_path_to_client) put-deploy \
--chain-name "casper-net-1" \
--secret-key /casper/casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/secret_key.pem \
--payment-amount 2500000000 \
--session-path <PATH> \
$(get_path_to_client) put-txn session \
--node-address http://localhost:11101
--chain-name casper-net-1 \
--pricing-mode fixed \
--gas-price-tolerance 10 \
--standard-payment true \
--category install-upgrade
--payment-amount 2500000000 \
--secret-key /casper/casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/secret_key.pem \
--transaction-path <PATH> \
--session-entry-point <Name of the entry point> \
```

The response will return something similar to the following information. Note the `deploy_hash`:
The response will return something similar to the following information. Note the `transaction_hash`:

```
{
"id": 4824893960188648146,
"jsonrpc": "2.0",
"result": {
"api_version": "1.0.0",
"deploy_hash": "8e6309cc37bc58d8fedc1094ee1bd264a636d39fc0e05b5e1d72d98f7b6faf13"
"jsonrpc": "2.0",
"id": 2954769041950332810,
"result": {
"api_version": "2.0.0",
"transaction_hash": {
"Version1": "cb34519aa21a1c285aceeaf808ed7745e1f79d0b69dacb67d05e111281923c07"
}
}
}
```

## Verifying Deploy Execution
## Verifying Transaction Execution

The previous command sent the `Transaction` to the NCTL network, but we recommend verifying its execution before continuing. The `transaction_hash` received in the response allows you to query the `Transaction`'s status.

The previous command sent the `Deploy` to the NCTL network, but we recommend verifying deploy execution before continuing. The `deploy_hash` received in the response allows you to query the `Deploy`'s status.
To query the `Transaction`'s status, you will pass both the `transaction_hash` and the same `node-address` from above using the following command. This will return either an error message in the event of failure or the `Transaction` details if it succeeds.

To query the `Deploy`'s status, you will pass both the `deploy_hash` and the same `node-address` from above using the following command. This will return either an error message in the event of failure or the `Deploy` details if it succeeds.
```
$(get_path_to_client) get-deploy 8e6309cc37bc58d8fedc1094ee1bd264a636d39fc0e05b5e1d72d98f7b6faf13 -n http://localhost:11101
$(get_path_to_client) get-txn cb34519aa21a1c285aceeaf808ed7745e1f79d0b69dacb67d05e111281923c07 -n http://localhost:11101
```

## Interacting with the Installed Contract

Once your NCTL network executes your `Deploy`, you can test the functionality of the installed contract. To do so, you will first need to identify any arguments to pass to the contract, starting with the `ContractHash` itself. This hash identifies the contract and allows you to target the included entry points. As we used the pre-established node-1 account to [send the `Deploy`](../../developers/cli/sending-transactions.md), we can retrieve the `ContractHash` from the node-1 account information. To do so, we will use the following command with a node address and the `PublicKey` of the node in question.

Once your NCTL network executes your `Transaction`, you can test the functionality of the installed contract. To do so, you will first need to identify any arguments to pass to the contract, starting with the `ContractHash` itself. This hash identifies the contract and allows you to target the included entry points. As we used the pre-established node-1 account (addresable entity) to [send the `Transaction`](../../developers/cli/sending-transactions.md), we can retrieve the `ContractHash` from the node-1 account information. To do so, we will use the following command with a node address and the `PublicKey` of the node in question.

```
$(get_path_to_client) get-account-info \
$(get_path_to_client) get-entity \
--node-address http://localhost:11101 \
--public-key /casper/casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/public_key.pem
--entity-identifier /casper/casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/public_key.pem
```

This command will return information pertaining to the account, including the `NamedKeys`. The `ContractHash` of the contract to be tested will appear here. The process of calling the contract is similar to that of installing it, as they are both accomplished through sending a `Deploy`. In this instance, you will need the following information:
This command will return information pertaining to the account, including the `NamedKeys`. The `ContractHash` of the contract to be tested will appear here. The process of calling the contract is similar to that of installing it, as they are both accomplished through sending a `Transaction`. In this instance, you will need the following information:

- The **node-address**, entered in this instance using `--node-address http://localhost:11101`

* The **node address**, entered in this instance using `--node-address http://localhost:11101`
- The **chain-name**, entered in this instance using `--chain-name casper-net-1` The **pricing-mode** used to identify the payment mode chosen to execute the transaction.

* The **chain name**, entered in this instance using `--chain-name "casper-net-1"`
- The **payment-amount** for this `Transaction` in motes, which may need to be adjusted depending on cost and network [chainspec](../../concepts/glossary/C.md#chainspec). In this instance, we will use `--payment-amount 500000000`.

* The **payment amount** for this `Deploy` in motes, which may need to be adjusted depending on cost and network [chainspec](../../concepts/glossary/C.md#chainspec). In this instance, we will use `--payment-amount 500000000`
- The **gas-price-tolerance** the maximum gas price that the user is willing to pay for the transaction.

* The **session path**, defining the location of the Wasm bearing file for the `Deploy`. It appears in our example as `--session-path <PATH>` but you must define the path to your specific file.
- The **standard-payment** flag to determine if this transaction uses standard or custom payment.

* Any **session arguments** specific to the contract that you are testing. Multiple instances of `--session-arg` may be used as necessary to provide values to the contract, including the `ContractHash` you acquired above. In the example below, you will see a demonstration of the `ContractHash` as a session argument as `--session-arg "contract_key:key='hash-8c13aaeef50ae7f447ee21276965c31cfa45c4ea3abb03d35d078cdd6a40e4a'"`
- The **secret-key** path. If not provided, the transaction will not be signed and will remain invalid until signed, for example by running the `sign-transaction` subcommand.

- The **entity-address** formatted string representing an addressable entity address. Our contract is a addresable and invocable entity.

- The **session-entry-point** name of the method that will be used when calling the session contract. This is any of the entry points that are defined in our smart contract.

- Any **session arguments** specific to the contract that you are testing. Multiple instances of `--session-arg` may be used as necessary to provide values to the entry points of the smart contract.

```
$(get_path_to_client) put-deploy \
$(get_path_to_client) put-txn \
--node-address http://localhost:11101 \
--chain-name "casper-net-1" \
--chain-name casper-net-1 \
--gas-price-tolerance 10 \
--payment-amount 500000000 \
--session-path <PATH> \
--session-arg "contract_key:key='hash-8c13aaeef50ae7f447ee21276965c31cfa45c4ea3abb03d35d078cdd6a40e4a'"
--standard-payment true \
--secret-key /casper/casper-node/utils/nctl/assets/net-1/nodes/node-1/keys/secret_key.pem \
--session-entry-point <Name of the entry point> \
--entity-address entity-contract-8c13aaeef50ae7f447ee21276965c31cfa45c4ea3abb03d35d078cdd6a40e4a
```

## Verifying Correct Contract Behavior

After calling your installed contract, you can verify that the contract behaved as expected by observing the associated change in [global state](../../developers/cli/installing-contracts.md#querying-global-state). Depending on how your contract functions, this can have different meanings and results. If we use our donation contract from the [basic smart contract tutorial](../../developers/writing-onchain-code/simple-contract.md), the NCTL process would have the following flow:

1) Send a `Deploy` to install the "Donation" smart contract.
1. Send a `Transaction` to install the "Donation" smart contract.

2) Verify the execution of the `Deploy`.
2. Verify the execution of the `Transaction`.

3) Interact with the installed contract using an additional `Deploy` that calls one or several of the entry points. For example, calling the `donate` entry point to donate an amount to the fundraising purse.
3. Interact with the installed contract using an additional `Transaction` that calls one or several of the entry points. For example, calling the `donate` entry point to donate an amount to the fundraising purse.

4) Verify the associated change in global state. Namely, an increase in the balance of the fundraising purse.
4. Verify the associated change in global state. Namely, an increase in the balance of the fundraising purse.
Loading