diff --git a/RELEASING.md b/RELEASING.md index c3783988..e95ad052 100644 --- a/RELEASING.md +++ b/RELEASING.md @@ -8,16 +8,23 @@ Releasing checklist: (3) Checkout the `main` branch. This is the only releasable branch. -(4) Create a tag for the release. +(4) Create and push a release branch. + +```sh +git checkout -b release-v0.12.0 +git push release-v0.12.0 +``` + +(5) Create a tag for the release. ```sh git tag v0.12.0 ``` -(5) Push the tag to the main repository, [triggering the CI and release process](https://github.com/OpenZeppelin/nile/blob/951cf2403aa58a9b58c3c1a793b51cd5c58cb56e/.github/workflows/ci.yml#L55). +(6) Push the tag to the main repository, [triggering the CI and release process](https://github.com/OpenZeppelin/nile/blob/951cf2403aa58a9b58c3c1a793b51cd5c58cb56e/.github/workflows/ci.yml#L55). ```sh git push origin v0.12.0 ``` -(6) Finally, go to the repo's [releases page](https://github.com/OpenZeppelin/nile/releases/) and [create a new one](https://github.com/OpenZeppelin/nile/releases/new) with the new tag and the `main` branch as target. +(7) Finally, go to the repo's [releases page](https://github.com/OpenZeppelin/nile/releases/) and [create a new one](https://github.com/OpenZeppelin/nile/releases/new) with the new tag and the `main` branch as target. diff --git a/docs/modules/ROOT/pages/cli.adoc b/docs/modules/ROOT/pages/cli.adoc index 441b807b..2f484dc4 100644 --- a/docs/modules/ROOT/pages/cli.adoc +++ b/docs/modules/ROOT/pages/cli.adoc @@ -3,105 +3,15 @@ :imports: link:https://starknet.io/docs/how_cairo_works/imports.html?highlight=cairo%20path#import-search-paths[Import search paths] :status: link:#status[status] -== CLI Reference += CLI Reference Here you can find a complete reference of the core commands Nile provides by default. -[.contract-index] -.Transactions --- -* xref:#setup[`++setup++`] -* xref:#declare[`++declare++`] -* xref:#deploy[`++deploy++`] -* xref:#send[`++send++`] -* xref:#status[`++status++`] -* xref:#debug[`++debug++`] --- - -[.contract-index] -.Queries --- -* xref:#call[`++call++`] -* xref:#get-nonce[`++get-nonce++`] -* xref:#get-balance[`++get-balance++`] --- - -[.contract-index] -.Project management --- -* xref:#init[`++init++`] -* xref:#node[`++node++`] -* xref:#compile[`++compile++`] -* xref:#run[`++run++`] -* xref:#clean[`++clean++`] -* xref:#version[`++version++`] --- - -[.contract-index] -.Utils --- -* xref:#get-accounts[`++get-accounts++`] -* xref:#counterfactual-address[`++counterfactual-address++`] --- +== Transaction execution -[.contract-item] -[[node]] -==== `[.contract-item-name]#++nile node++#` +Commands for executing or querying the status of a transaction. -Run a local {starknet-devnet} node. - -===== Options - -- `*--host*` -+ -Specify the address to listen at. -+ -Defaults to 127.0.0.1 (use the address the program outputs on start). -- `*--port*` -+ -Specify the port to listen at. Defaults to 5050. -- `*--seed*` -+ -Specify the seed for randomness of accounts to be deployed. -- `*--lite-mode*` -+ -Applies all lite-mode optimizations by disabling features such as block hash and deploy hash calculation. - -[.contract-item] -[[compile]] -==== `[.contract-item-name]#++nile compile [PATH_TO_CONTRACT]++#` - -Compile Cairo contracts. - -Compilation artifacts are written into the `artifacts/` directory. - -===== Arguments - -- `*PATH_TO_CONTRACT*` -+ -Specify the path to a contract for compiling. - -===== Options - -- `*--directory*` -+ -Specify a directory to compile contracts from. -- `*--account_contract*` -+ -As of {cairo-lang} v0.8.0, users must compile account contracts with the `--account_contract` flag. Nile automatically inserts the flag if the contract's name ends with Account. i.e. `Account.cairo`, `EthAccount.cairo`. Otherwise, the flag must be included by the user. -+ -[,sh] ----- -nile compile contracts/NewAccountType.cairo --account_contract # compiles account contract ----- -- `*--cairo_path*` -+ -Specify which directories the compiler must use to resolve imports from Cairo. -+ -TIP: Check {imports} from StarkNet documentation. -- `*--disable-hint-validation*` -+ -Compile allowing unwhitelisted hints. +=== `setup` [.contract-item] [[setup]] @@ -127,8 +37,16 @@ Specify the private key that will own the account to be deployed. Looks for an e include::snippets.adoc[tag=network-options] + +include::snippets.adoc[tag=salt] ++ +include::snippets.adoc[tag=max-fee] ++ +include::snippets.adoc[tag=query-options] ++ include::snippets.adoc[tag=status-options] +=== `declare` + [.contract-item] [[declare]] ==== `[.contract-item-name]#++nile declare ++#` @@ -148,19 +66,22 @@ Specify the name of the contract artifact to be declared. include::snippets.adoc[tag=network-options] + -Default to localhost. -- `*--max_fee*` +include::snippets.adoc[tag=max-fee] ++ +- `*--alias*` ++ +The alias for registering the declared class_hash (DEPRECATED). + -Specify the max fee you are willing to pay for the transaction. - `*--overriding_path*` + Override the directory path for artifacts discovery. -- `*--token*` + -Used for declaring contracts to Alpha Mainnet. +include::snippets.adoc[tag=query-options] + include::snippets.adoc[tag=status-options] +=== `deploy` + [.contract-item] [[deploy]] ==== `[.contract-item-name]#++nile deploy [arg1, arg2...]++#` @@ -188,13 +109,15 @@ Optional calldata arguments for the constructor. include::snippets.adoc[tag=network-options] + -Default to localhost. -- `*--max_fee*` +include::snippets.adoc[tag=salt] ++ +include::snippets.adoc[tag=max-fee] + -Specify the max fee you are willing to pay for the transaction. -- `*--salt*` +- `*--alias*` ++ +Specify the alias for Nile local registration purposes. This allows you to interact with +the contract later without using the address directly. + -Set the base salt for address generation. - `*--unique*` + Specify that the account address should be taken into account for target address generation. @@ -204,39 +127,12 @@ Override artifact abi to be registered. Useful for proxies. - `*--deployer_address*` + Specify the deployer contract if needed. -- `*--ignore_account*` -+ -Deploy without using an account (DEPRECATED). -- `*--token*` + -Used for deploying contracts to Alpha Mainnet. +include::snippets.adoc[tag=query-options] + include::snippets.adoc[tag=status-options] - -[.contract-item] -[[call]] -==== `[.contract-item-name]#++nile call [arg1, arg2...]++#` - -Perform reading operations against a network. - -===== Arguments - -- `*CONTRACT_ID*` -+ -Specify the contract to call (either alias or address). -- `*METHOD*` -+ -Specify the method to call. -- `*ARGS*` -+ -Optional calldata arguments for the method to query. - -===== Options - -include::snippets.adoc[tag=network-options] -+ -Default to localhost. +=== `send` [.contract-item] [[send]] @@ -263,36 +159,13 @@ Optional calldata arguments for the method to execute. include::snippets.adoc[tag=network-options] + -Default to localhost. -- `*--max_fee*` +include::snippets.adoc[tag=max-fee] + -Specify the max fee you are willing to pay for the transaction. -- `*--simulate*` and `*--estimate_fee*` -+ -Flags for querying the network without executing the transaction. +include::snippets.adoc[tag=query-options] + include::snippets.adoc[tag=status-options] - -[.contract-item] -[[counterfactual-address]] -==== `[.contract-item-name]#++nile counterfactual-address ++#` - -Precompute the deployment address of an Account contract. - -===== Arguments - -- `*PRIVATE_KEY_ALIAS*` -+ -Specify the alias representing the private key to be used. - -===== Options - -- `*--salt*` -+ -Specify the salt for the address generation. -+ -Default to 0. +=== `status` [.contract-item] [[status]] @@ -310,7 +183,6 @@ Specify the hash of the transaction to query. include::snippets.adoc[tag=network-options] + -Default to localhost. - `*--track*` + Continue probing the network in case of pending transaction states. @@ -331,27 +203,35 @@ Default to `.deployments.txt`. Alias for `nile status --debug`. +== Queries + +Utilities for querying the blockchain. + +=== `call` + [.contract-item] -[[get-accounts]] -==== `[.contract-item-name]#++nile get-accounts++#` +[[call]] +==== `[.contract-item-name]#++nile call [arg1, arg2...]++#` -Retrieve a list of ready-to-use accounts which allows for easy scripting integration. +Perform reading operations against a network. -[NOTE] -==== -The list of accounts includes only those that exist in the local `.accounts.json` file. In a recent release we added a flag to the command, to get predeployed accounts if the network you are connected to is a starknet-devnet instance. +===== Arguments -Sending transactions through predeployed accounts can be done through scripting, but the current CLI version doesn't allow using these accounts for `nile send`. -==== +- `*CONTRACT_ID*` ++ +Specify the contract to call (either alias or address). +- `*METHOD*` ++ +Specify the method to call. +- `*ARGS*` ++ +Optional calldata arguments for the method to query. ===== Options include::snippets.adoc[tag=network-options] -+ -Default to localhost. -- `*--predeployed*` -+ -Query a devnet node for predeployed accounts. + +=== `get-nonce` [.contract-item] [[get-nonce]] @@ -368,8 +248,8 @@ Specify the address of the contract to query. ===== Options include::snippets.adoc[tag=network-options] -+ -Default to localhost. + +=== `get-balance` [.contract-item] [[get-balance]] @@ -386,8 +266,83 @@ Specify the address of the contract to query. ===== Options include::snippets.adoc[tag=network-options] + +== Project management + +Utilities for managing the project. + +=== `init` + +[.contract-item] +[[init]] +==== `[.contract-item-name]#++nile init++#` + +Scaffold a simple Nile project. + +=== `node` + +[.contract-item] +[[node]] +==== `[.contract-item-name]#++nile node++#` + +Run a local {starknet-devnet} node. + +===== Options + +- `*--host*` ++ +Specify the address to listen at. + -Default to localhost. +Defaults to 127.0.0.1 (use the address the program outputs on start). +- `*--port*` ++ +Specify the port to listen at. Defaults to 5050. +- `*--seed*` ++ +Specify the seed for randomness of accounts to be deployed. +- `*--lite-mode*` ++ +Applies all lite-mode optimizations by disabling features such as block hash and deploy hash calculation. + +=== `compile` + +[.contract-item] +[[compile]] +==== `[.contract-item-name]#++nile compile [PATH_TO_CONTRACT]++#` + +Compile Cairo contracts. + +Compilation artifacts are written into the `artifacts/` directory. + +===== Arguments + +- `*PATH_TO_CONTRACT*` ++ +Specify the path to a contract for compiling. + +===== Options + +- `*--directory*` ++ +Specify a directory to compile contracts from. +- `*--account_contract*` ++ +As of {cairo-lang} v0.8.0, users must compile account contracts with the `--account_contract` flag. Nile automatically inserts the flag if the contract's name ends with Account. i.e. `Account.cairo`, `EthAccount.cairo`. Otherwise, the flag must be included by the user. ++ +[,sh] +---- +nile compile contracts/NewAccountType.cairo --account_contract # compiles account contract +---- +- `*--cairo_path*` ++ +Specify which directories the compiler must use to resolve imports from Cairo. ++ +TIP: Check {imports} from StarkNet documentation. +- `*--disable-hint-validation*` ++ +Compile allowing unwhitelisted hints. + +=== `run` [.contract-item] [[run]] @@ -404,8 +359,8 @@ Path to the script to run. ===== Options include::snippets.adoc[tag=network-options] -+ -Default to localhost. + +=== `clean` [.contract-item] [[clean]] @@ -413,14 +368,57 @@ Default to localhost. Deletes the `artifacts/` folder and deployments files. -[.contract-item] -[[init]] -==== `[.contract-item-name]#++nile init++#` - -Scaffold a simple Nile project. +=== `version` [.contract-item] [[version]] ==== `[.contract-item-name]#++nile version++#` Print out the Nile version. + +== Utils + +Other utilities. + +=== `get-accounts` + +[.contract-item] +[[get-accounts]] +==== `[.contract-item-name]#++nile get-accounts++#` + +Retrieve a list of ready-to-use accounts which allows for easy scripting integration. + +[NOTE] +==== +The list of accounts includes only those that exist in the local `.accounts.json` file. In a recent release we added a flag to the command, to get predeployed accounts if the network you are connected to is a starknet-devnet instance. + +Sending transactions through predeployed accounts can be done through scripting, but the current CLI version doesn't allow using these accounts for `nile send`. +==== + +===== Options + +include::snippets.adoc[tag=network-options] ++ +- `*--predeployed*` ++ +Query a devnet node for predeployed accounts. + +=== `counterfactual-address` + +[.contract-item] +[[counterfactual-address]] +==== `[.contract-item-name]#++nile counterfactual-address ++#` + +Precompute the deployment address of an Account contract. + +===== Arguments + +- `*PRIVATE_KEY_ALIAS*` ++ +Specify the alias representing the private key to be used. + +===== Options + +include::snippets.adoc[tag=salt] ++ +Default to 0. diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index 948af963..e330f868 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -21,6 +21,7 @@ Before installing Cairo on your machine, you need to install `gmp`: [,bash] ---- sudo apt install -y libgmp3-dev # linux +or brew install gmp # mac ---- @@ -137,22 +138,39 @@ nile counterfactual-address ACCOUNT_1 --salt 123 + NOTE: Different salts compute to different addresses, even with the same private key. + -. In production, you will need to fund this address with Ether to pay for the deployment fees, which will be mandatory in testnets soon. There are multiple bridges and faucets, like link:https://goerli.starkgate.starknet.io/[Starkgate] being implemented at the moment to support the developer experience. +. Estimate the fee for executing the transaction. + -For local development using a devnet node, you can use predeployed accounts to fund your address by using xref:scripts.adoc#transfer_funds_from_predeployed_devnet_account[this script]. +[,sh] +---- +nile setup ACCOUNT_1 --salt 123 --estimate_fee +---- ++ +[,sh] +---- +The estimated fee is: 52147932632842 WEI (0.000052 ETH). +Gas usage: 5063 +Gas price: 10299808934 WEI +---- ++ +In production, you will need to fund the counterfactual address with Ether to pay for the deployment fees, which will be mandatory in testnets soon. There are multiple bridges and faucets, like link:https://goerli.starkgate.starknet.io/[Starkgate] being implemented at the moment to support the developer experience. ++ +For local development using a devnet node, you can use predeployed accounts to fund your address by using xref:scripts.adoc#transfer_funds_from_a_predeployed_devnet_account[this script]. + . After funding the precomputed address, deploy the account using `nile setup`. + [,sh] ---- -nile setup ACCOUNT_1 --salt 123 +nile setup ACCOUNT_1 --salt 123 --max_fee 52147932632842 ---- + +NOTE: Nile will estimate the `max_fee` by default if this option is not set. This is valid for other commands +involving transaction execution, like `declare`, `send`, or `deploy`. ++ [IMPORTANT] ==== In StarkNet, users can deploy only previously declared contracts. {oz-account} is declared soon after every release in devnet, testnets and mainnet, but there could be an out-of-sync period between account update release and devnet release. Then you can declare the OZ Account using predeployed accounts through scripts. -Check xref:scripts.adoc#declare_account[Declare Account] script. +Check xref:scripts.adoc#declare_account[Declare the OZ Account] script. ==== ==== Deploying a contract diff --git a/docs/modules/ROOT/pages/nre.adoc b/docs/modules/ROOT/pages/nre.adoc index cdc0f5d6..78aab3a2 100644 --- a/docs/modules/ROOT/pages/nre.adoc +++ b/docs/modules/ROOT/pages/nre.adoc @@ -1,21 +1,13 @@ -== NRE Reference += NRE Reference -Here you can find a complete reference of the functions provided by the Nile Runtime Environment. +Here you can find a complete reference of the functions provided by the Nile Runtime Environment, and +a reference of the Account methods. -[.contract-index] -.Functions --- -* xref:#compile[`++compile++`] -* xref:#deploy[`++deploy++`] -* xref:#call[`++call++`] -* xref:#get_deployment[`++get_deployment++`] -* xref:#get_declaration[`++get_declaration++`] -* xref:#get_or_deploy_account[`++get_or_deploy_account++`] -* xref:#get_accounts[`++get_accounts++`] -* xref:#get_nonce[`++get_nonce++`] -* xref:#get_balance[`++get_balance++`] +== NRE API --- +Functions provided within the NRE object. + +=== `compile` [.contract-item] [[compile]] @@ -32,46 +24,7 @@ List of contracts to compile. + Specify a set of directories for the Cairo compiler to resolve imports. -[.contract-item] -[[deploy]] -==== `[.contract-item-name]#++deploy++#++(contract, arguments=None, alias=None, overriding_path=None, abi=None, mainnet_token=None, watch_mode=None) → (address, abi)++` - -Deploy a smart contract. - -WARNING: Deprecated in favor of deployments through accounts. - -===== Arguments - -- `*contract*` -+ -Contract to deploy. -- `*arguments*` -+ -List of arguments for the constructor (calldata). -- `*alias*` -+ -Alias for deployment registration. -- `*overriding_path*` -+ -Override for the path to artifacts and abis. -- `*abi*` -+ -Use a different abi for registration (useful for proxies). -- `*mainnet_token*` -+ -Token for mainnet deployments. -- `*watch_mode*` -+ -Either `track` or `debug` (check `status` command). - -===== Return values - -- `*address*` -+ -Address of the new contract. -- `*abi*` -+ -Abi registered in deployments. +=== `call` [.contract-item] [[call]] @@ -100,6 +53,8 @@ Override for the abi if necessary. + Output from the underlaying starknet cli call. +=== `get_deployment` + [.contract-item] [[get_deployment]] ==== `[.contract-item-name]#++get_deployment++#++(address_or_alias) → (address, abi)++` @@ -122,6 +77,8 @@ Registered contract address. + Registered contract abi. +=== `get_declaration` + [.contract-item] [[get_declaration]] ==== `[.contract-item-name]#++get_declaration++#++(hash_or_alias) → class_hash++` @@ -140,6 +97,8 @@ Contract identifier. + Declared contract class hash. +=== `get_or_deploy_account` + [.contract-item] [[get_or_deploy_account]] ==== `[.contract-item-name]#++get_or_deploy_account++#++(signer, watch_mode=None) → account++` @@ -159,7 +118,9 @@ Either None, track or debug. Block the execution to query the status of the depl - `*account*` + -Account matching the signer. +An link:#account_api[Account] instance matching the signer. + +=== `get_accounts` [.contract-item] [[get_accounts]] @@ -177,7 +138,9 @@ Get predeployed accounts from a starknet-devnet node. - `*accounts*` + -Registered accounts. +A list of registered link:#account_api[Accounts]. + +=== `get_nonce` [.contract-item] [[get_nonce]] @@ -197,6 +160,8 @@ Address of the contract to query. + Nonce of the contract. +=== `get_balance` + [.contract-item] [[get_balance]] ==== `[.contract-item-name]#++get_balance++#++(contract_address) → balance++` @@ -214,3 +179,208 @@ Address of the contract to query. - `*balance*` + Balance of the contract. + +== Account API + +Public API of the Account abstraction. + +=== `send` + +[.contract-item] +[[send]] +==== `[.contract-item-name]#++async send++#++(self, address_or_alias, method, calldata, nonce=None, max_fee=None) → transaction++` + +Return a Transaction instance representing an invoke transaction. + +===== Arguments + +- `*address_or_alias*` ++ +Target contract identifier (alias needs to be registered in deployments). +- `*method*` ++ +Method to execute. +- `*calldata*` ++ +Arguments for the call. +- `*nonce*` ++ +Account nonce. Is automatically computed when is left as `None`. +- `*max_fee*` ++ +The max fee you are willing to pay for the transaction execution. ++ +This value will be usually left as `None`, because +the returned transaction allows to estimate and update the fee later. + +===== Return values + +- `*transaction*` ++ +A link:#transaction_api[Transaction] instance. + +=== `declare` + +[.contract-item] +[[declare]] +==== `[.contract-item-name]#++async declare++#++(self, contract_name, nonce=None, max_fee=None, alias=None, overriding_path=None, nile_account=False) → transaction++` + +Return a Transaction instance representing a declare transaction. + +===== Arguments + +- `*contract_name*` ++ +The name of the contract to declare (for artifacts resolution). +- `*nonce*` ++ +Account nonce. Is automatically computed when is left as `None`. +- `*max_fee*` ++ +The max fee you are willing to pay for the transaction execution. ++ +This value will be usually left as `None`, because +the returned transaction allows to estimate and update the fee later. +- `*alias*` ++ +The alias for registering the declared class_hash (DEPRECATED). +- `*overriding_path*` ++ +Path override for artifacts and abi resolution. +- `*nile_account*` ++ +Wheter to use the OZ account artifact. + +===== Return values + +- `*transaction*` ++ +A link:#transaction_api[Transaction] instance. + +=== `deploy_contract` + +[.contract-item] +[[deploy_contract]] +==== `[.contract-item-name]#++async deploy_contract++#++(self, contract_name, salt, unique, calldata, nonce=None, max_fee=None, deployer_address=None, alias=None, overriding_path=None, abi=None) → transaction++` + +Return a Transaction instance representing a deploy through UDC transaction. See the link:https://docs.openzeppelin.com/contracts-cairo/udc#api_specification#[Universal Deployer Contract] documentation. + +===== Arguments + +- `*contract_name*` ++ +The name of the contract to deploy (for artifacts resolution). +- `*salt*` and `*unique*` ++ +UDC specific arguments for address generation. +- `*calldata*` ++ +Contract to deploy constructor arguments. +- `*nonce*` ++ +Account nonce. Is automatically computed when is left as `None`. +- `*max_fee*` ++ +The max fee you are willing to pay for the transaction execution. ++ +This value will be usually left as `None`, because +the returned transaction allows to estimate and update the fee later. +- `*deployer_address*` ++ +Specify a different deployer address. ++ +Default to the UDC address. +- `*alias*` ++ +The alias for deployment registration. +- `*overriding_path*` ++ +Path override for artifacts and abi resolution. +- `*abi*` ++ +Override for the contract ABI (for deployment registration). + +===== Return values + +- `*transaction*` ++ +A link:#transaction_api[Transaction] instance. + +== Transaction API + +Public API of the Transaction abstraction. + +=== `estimate_fee` + +[.contract-item] +[[estimate_fee]] +==== `[.contract-item-name]#++async estimate_fee++#++(self) → max_fee++` + +Return the estimated fee of executing the transaction. + +===== Return values + +- `*max_fee*` ++ +The estimated fee. + +=== `simulate` + +[.contract-item] +[[simulate]] +==== `[.contract-item-name]#++async simulate++#++(self) → trace++` + +Return a trace of the simulated execution. + +===== Return values + +- `*trace*` ++ +An object representing the simulation. + +=== `execute` + +[.contract-item] +[[execute]] +==== `[.contract-item-name]#++async execute++#++(self, watch_mode=None) → (tx_status, log_output)++` + +Execute the transaction. + +===== Arguments + +- `*watch_mode*` ++ +Allow waiting for the transaction to be included in a block. +Either `None`, `track` or `debug`. `track` to continue probing the network in case of pending transaction states. `debug` to use locally available contracts to make error messages from rejected transactions more explicit (Implies `track`). ++ +Default to `None` (non blocking). + +===== Return values + +- `*tx_status*` ++ +A Transaction Status object. ++ +- `*log_output*` ++ +A string representing the output of the inner call. + +=== `update_fee` + +[.contract-item] +[[update_fee]] +==== `[.contract-item-name]#++update_fee++#++(self, max_fee) → self++` + +Update the max_fee modifying the transaction hash. + +===== Arguments + +- `*max_fee*` ++ +The new max_fee to set. + +===== Return values + +- `*self*` ++ +Return self to allow chaining with execute. diff --git a/docs/modules/ROOT/pages/scripts.adoc b/docs/modules/ROOT/pages/scripts.adoc index 0ce98906..1ef48e34 100644 --- a/docs/modules/ROOT/pages/scripts.adoc +++ b/docs/modules/ROOT/pages/scripts.adoc @@ -41,43 +41,64 @@ For a full reference of NRE exposed members check the xref:nre.adoc[NRE Referenc In this section you can find some potentially helpful script examples. [#declare_account] -=== Declare Account +=== Declare the OZ account -Useful if you need to deploy an account in devnet, for previous declaration: +Useful if you need to deploy the account in a local devnet node, for previous declaration: [,python] ---- -# script.py +# scripts/declare_oz_account.py async def run(nre): accounts = await nre.get_accounts(predeployed=True) declarer_account = accounts[0] # nile_account flag tells Nile to use its pre-packed artifact - output = await declarer_account.declare("Account", nile_account=True) - print(output) + # + # If we don't pass a max_fee, nile will estimate the transaction + # fee by default. This line is equivalent to: + # + # tx = await declarer_account.declare("Account", max_fee=0, nile_account=True) + # max_fee = await tx.estimate_fee() + # tx.update_fee(max_fee) + # + # Note that tx.update_fee will update tx.hash and tx.max_fee members + tx = await declarer_account.declare("Account", nile_account=True) + + tx_status, *_ = await tx.execute(watch_mode="track") + + print(tx_status.status, tx_status.error_message or "") ---- -=== Transfer funds from predeployed devnet account +=== Transfer funds from a predeployed devnet account Useful for funding addresses in devnet: [,python] ---- +# scripts/transfer_funds.py from nile.common import ETH_TOKEN_ADDRESS +from nile.utils import to_uint, hex_address async def run(nre): - accounts = await nre.get_accounts(predeployed=True) - account = accounts[0] + accounts = await nre.get_accounts(predeployed=True) + account = accounts[0] + + # define the recipient address + recipient = "0x05a0ca51cbc03e5ec8d9fad116f8737a6afe2613b3128ebd515643a1a5e5c52d" + + # define the amount to transfer + amount = 2 * 10 ** 18 - # define the recipient address - recipient = "0x053edde5384e39bad137d3c4130c708fb96ee28a4c80bf28049c486d3f369" + print( + f"Transferring {amount} WEI\n" + f"from {hex_address(account.address)}\n" + f"to {recipient}\n" + ) - # define the amount to transfer (uint256 format) - amount = [2 * 10 ** 18, 0] + # If we don't pass a max_fee, nile will estimate the transaction fee by default + tx = await account.send(ETH_TOKEN_ADDRESS, "transfer", [recipient, *to_uint(amount)]) - print(f"Transferring {amount} to {recipient} from {hex(account.address)}") + tx_status, *_ = await tx.execute(watch_mode="track") - # send the transfer transaction - output = await account.send(ETH_TOKEN_ADDRESS, "transfer", [recipient, *amount]) - print(output) + print(tx_status.status, tx_status.error_message or "") ---- diff --git a/docs/modules/ROOT/pages/snippets.adoc b/docs/modules/ROOT/pages/snippets.adoc index 065fb103..ce41466f 100644 --- a/docs/modules/ROOT/pages/snippets.adoc +++ b/docs/modules/ROOT/pages/snippets.adoc @@ -12,4 +12,22 @@ Default to `localhost`. - `*--debug*` and `*--track*` + Watch the status of the account deployment transaction. See the {status} command for a complete description. -// tag::status-options[] +// end::status-options[] + +// tag::query-options[] +- `*--simulate*` and `*--estimate_fee*` ++ +Flags for querying the network without executing the transaction. +// end::query-options[] + +// tag::max-fee[] +- `*--max_fee*` ++ +Specify the max fee you are willing to pay for the transaction. +// end::max-fee[] + +// tag::salt[] +- `*--salt*` ++ +Specify the salt for the address generation. +// end::salt[] diff --git a/src/nile/base_project/.gitignore b/src/nile/base_project/.gitignore index 1154e8a0..6e0963b6 100644 --- a/src/nile/base_project/.gitignore +++ b/src/nile/base_project/.gitignore @@ -133,3 +133,6 @@ dmypy.json # vscode project settings .vscode/ + +# nile project +artifacts/ diff --git a/src/nile/cli.py b/src/nile/cli.py index aa1e550f..457c53bd 100644 --- a/src/nile/cli.py +++ b/src/nile/cli.py @@ -17,8 +17,8 @@ from nile.core.run import run as run_command from nile.core.test import test as test_command from nile.core.types.account import get_counterfactual_address, try_get_account -from nile.core.types.signer import Signer from nile.core.version import version as version_command +from nile.signer import Signer from nile.utils import hex_address, normalize_number, shorten_address from nile.utils.get_accounts import get_accounts as get_accounts_command from nile.utils.get_accounts import ( @@ -79,14 +79,6 @@ def query_option(f): return f -def mainnet_token_option(f): - """Configure TOKEN option for the cli.""" - return click.option( - "--token", - help="Used for deploying contracts in Alpha Mainnet.", - )(f) - - async def run_transaction(tx, query_flag, watch_mode): """Execute or simulate a transaction.""" if query_flag == "estimate_fee": @@ -143,8 +135,8 @@ async def run(ctx, path, network): @click.argument("signer", nargs=1) @click.argument("contract_name", nargs=1) @click.argument("params", nargs=-1) -@click.option("--max_fee", nargs=1) -@click.option("--salt", nargs=1, default=0) +@click.option("--max_fee", type=int, nargs=1) +@click.option("--salt", type=int, nargs=1, default=0) @click.option("--unique", is_flag=True) @click.option("--alias") @click.option("--abi") @@ -176,8 +168,8 @@ async def deploy( salt, unique, params, - alias, deployer_address=deployer_address, + alias=alias, max_fee=max_fee, abi=abi, ) @@ -188,7 +180,7 @@ async def deploy( @cli.command() @click.argument("signer", nargs=1) @click.argument("contract_name", nargs=1) -@click.option("--max_fee", nargs=1) +@click.option("--max_fee", type=int, nargs=1) @click.option("--alias") @click.option("--overriding_path") @click.option("--nile_account", is_flag=True) @@ -213,8 +205,8 @@ async def declare( if account is not None: transaction = await account.declare( contract_name, - alias=alias, max_fee=max_fee, + alias=alias, overriding_path=overriding_path, nile_account=nile_account, ) @@ -224,8 +216,8 @@ async def declare( @cli.command() @click.argument("signer", nargs=1) -@click.option("--salt", nargs=1) -@click.option("--max_fee", nargs=1) +@click.option("--salt", type=int, nargs=1) +@click.option("--max_fee", type=int, nargs=1) @network_option @query_option @watch_option @@ -241,7 +233,7 @@ async def setup(ctx, signer, network, salt, max_fee, query, watch_mode): @cli.command() @click.argument("signer", nargs=1) -@click.option("--salt", nargs=1, default=None) +@click.option("--salt", type=int, nargs=1) @enable_stack_trace def counterfactual_address(ctx, signer, salt): """Precompute the address of an Account contract.""" @@ -257,7 +249,7 @@ def counterfactual_address(ctx, signer, salt): @click.argument("address_or_alias", nargs=1) @click.argument("method", nargs=1) @click.argument("params", nargs=-1) -@click.option("--max_fee", nargs=1) +@click.option("--max_fee", type=int, nargs=1) @network_option @query_option @watch_option diff --git a/src/nile/common.py b/src/nile/common.py index ac1ed899..bd1ef0fb 100644 --- a/src/nile/common.py +++ b/src/nile/common.py @@ -24,7 +24,7 @@ DECLARATIONS_FILENAME = "declarations.txt" ACCOUNTS_FILENAME = "accounts.json" NODE_FILENAME = "node.json" -RETRY_AFTER_SECONDS = 30 +RETRY_AFTER_SECONDS = 20 TRANSACTION_VERSION = 1 QUERY_VERSION_BASE = 2**128 QUERY_VERSION = QUERY_VERSION_BASE + TRANSACTION_VERSION diff --git a/src/nile/core/run.py b/src/nile/core/run.py index 8310290a..144521f3 100644 --- a/src/nile/core/run.py +++ b/src/nile/core/run.py @@ -9,7 +9,7 @@ async def run(path, network): """Run nile scripts passing on the NRE object.""" logger = logging.getLogger() - logger.disabled = True + logger.setLevel(logging.ERROR) script = SourceFileLoader("script", path).load_module() nre = NileRuntimeEnvironment(network) await script.run(nre) diff --git a/src/nile/core/types/account.py b/src/nile/core/types/account.py index a5592fd7..0c60b0ae 100644 --- a/src/nile/core/types/account.py +++ b/src/nile/core/types/account.py @@ -12,7 +12,6 @@ is_alias, normalize_number, ) -from nile.core.types.signer import Signer from nile.core.types.transactions import ( DeclareTransaction, DeployAccountTransaction, @@ -26,6 +25,7 @@ ) from nile.core.types.udc_helpers import create_udc_deploy_transaction from nile.core.types.utils import get_counterfactual_address, get_execute_calldata +from nile.signer import Signer from nile.utils.get_nonce import get_nonce_without_log as get_nonce load_dotenv() @@ -152,8 +152,8 @@ async def send( async def declare( self, contract_name, - max_fee=None, nonce=None, + max_fee=None, alias=None, overriding_path=None, nile_account=False, @@ -190,10 +190,10 @@ async def deploy_contract( salt, unique, calldata, - alias, - max_fee=None, nonce=None, + max_fee=None, deployer_address=None, + alias=None, overriding_path=None, abi=None, ): diff --git a/src/nile/core/types/signer.py b/src/nile/signer.py similarity index 100% rename from src/nile/core/types/signer.py rename to src/nile/signer.py diff --git a/src/nile/utils/__init__.py b/src/nile/utils/__init__.py index 90f512f2..cd81dd2a 100644 --- a/src/nile/utils/__init__.py +++ b/src/nile/utils/__init__.py @@ -2,7 +2,6 @@ # flake8: noqa from .common import ( - _pad_hex_to, add_uint, div_rem_uint, felt_to_str, diff --git a/src/nile/utils/status.py b/src/nile/utils/status.py index e10df79b..6e93082e 100644 --- a/src/nile/utils/status.py +++ b/src/nile/utils/status.py @@ -117,7 +117,10 @@ def _abi_to_path(filename): def _locate_error_lines_with_abis(file, addresses, to_contract): contracts = [] if not os.path.isfile(file): - raise IOError(f"Contracts file {file} not found.") + raise IOError( + f"Contracts file {file} not found " + "while trying to debug REJECTED transaction." + ) with open(file) as file_stream: for line_idx, line in enumerate(file_stream): diff --git a/tests/core/types/test_account.py b/tests/core/types/test_account.py index 08f7a463..7dc26674 100644 --- a/tests/core/types/test_account.py +++ b/tests/core/types/test_account.py @@ -255,9 +255,9 @@ async def test_deploy_contract( salt, unique, calldata, - alias, - max_fee, nonce=nonce, + max_fee=max_fee, + alias=alias, deployer_address=deployer_address, overriding_path=overriding_path, abi=abi, diff --git a/tests/core/types/test_signer.py b/tests/core/types/test_signer.py index bc9d2a04..18e9b96d 100644 --- a/tests/core/types/test_signer.py +++ b/tests/core/types/test_signer.py @@ -14,8 +14,8 @@ from starkware.starknet.testing.starknet import Starknet from nile.common import TRANSACTION_VERSION -from nile.core.types.signer import Signer from nile.core.types.utils import from_call_to_call_array +from nile.signer import Signer PRIVATE_KEY = 12345678987654321 SIGNER = Signer(PRIVATE_KEY) diff --git a/tests/mocks/mock_account.py b/tests/mocks/mock_account.py index 12ab9219..e743ab65 100644 --- a/tests/mocks/mock_account.py +++ b/tests/mocks/mock_account.py @@ -4,7 +4,7 @@ from nile.common import normalize_number from nile.core.types.account import Account -from nile.core.types.signer import Signer +from nile.signer import Signer MOCK_ADDRESS = 0x890