diff --git a/docs/neo-n3/README.md b/docs/neo-n3/README.md index 6b9c357..cf15d81 100644 --- a/docs/neo-n3/README.md +++ b/docs/neo-n3/README.md @@ -11,9 +11,7 @@

neow3j 3.23.0

-Neow3j is a development toolkit that provides easy and reliable tools to build Neo dApps and Smart Contracts using the Java -platform (Java, Kotlin, Android). It is an open-source project developed by the Neo community and maintained by -[AxLabs](https://axlabs.com). +Neow3j is a development toolkit that provides easy and reliable tools to build Neo dApps and Smart Contracts using the Java platform (Java, Kotlin, Android). It is an open-source project developed by the Neo community and maintained by [AxLabs](https://axlabs.com). @@ -43,13 +41,11 @@ platform (Java, Kotlin, Android). It is an open-source project developed by the * Smart contract invocations * Smart contract deployment * Smart contract development and compilation in Java -* Android support from API 24, which covers [~49%](https://developer.android.com/about/dashboards/) -of all active Android devices ([~1 billion devices](https://www.youtube.com/watch?v=vWLcyFtni6U#t=2m46s)) +* Android support from API 24, which covers [~49%](https://developer.android.com/about/dashboards/) of all active Android devices ([~1 billion devices](https://www.youtube.com/watch?v=vWLcyFtni6U#t=2m46s)) ## Quickstart -Neow3j is composed of an **SDK** for dApp development and a **devpack** for smart contract development. -The following sections describes how to get started with them. +Neow3j is composed of an **SDK** for dApp development and a **devpack** for smart contract development. The following sections describes how to get started with them. ### SDK @@ -73,8 +69,7 @@ __Maven__ ### Devpack -The neow3j devpack is a Java library that provides the Neo-specific functionality required to write smart contracts. If -you want to play around with the devpack, add the `io.neow3j:devpack` dependency to your project. +The neow3j devpack is a Java library that provides the Neo-specific functionality required to write smart contracts. If you want to play around with the devpack, add the `io.neow3j:devpack` dependency to your project. __Gradle__ @@ -92,18 +87,13 @@ __Maven__ ``` -For information on how to compile a smart contract hop over to the -[Setup & Compilation](neo-n3/smart_contract_development/setup_and_compilation.md) section. +For information on how to compile a smart contract hop over to the [Setup & Compilation](neo-n3/smart_contract_development/setup_and_compilation.md) section. ## Requirements Neow3j requires **Java 8** or higher. For Android applications this implies the use of API level >= 24. -Neow3j does **not include a blockchain node**. I.e., it does not synchronize with other nodes nor store or verify -blockchain information locally. It depends on a connection to a Neo node to retrieve blockchain information. If you want -to run your own node check out the [official documentation](https://docs.neo.org/v3/docs/en-us/node/introduction.html) -on how to set one up. For local development we recommend using -[Neo Express](https://github.com/neo-project/neo-express). +Neow3j does **not include a blockchain node**. I.e., it does not synchronize with other nodes nor store or verify blockchain information locally. It depends on a connection to a Neo node to retrieve blockchain information. If you want to run your own node check out the [official documentation](https://docs.neo.org/docs/n3/node/Introduction.html) on how to set one up. For local development we recommend using [Neo Express](https://github.com/neo-project/neo-express). ## Why the name "neow3j"? 🤔 @@ -113,15 +103,9 @@ Well... then, it was simply natural to imagine [Bongo Cat](https://knowyourmeme. ## Versioning -First of all, don't be confused by the number *3* in the name *neow3j*. It is not related to the -version of Neo as explained above. +First of all, don't be confused by the number *3* in the name *neow3j*. It is not related to the version of Neo as explained above. -Versioning of neow3j partially follows an adapted variant of semantic versioning. To be consistent -with Neo's major versions, neow3j keeps the first number fixed to the current Neo version. I.e., -neow3j 3.x.x for versions of the library that are compatible with Neo N3. The semantics of the -version number is therefore shifted to the right by one position. Incrementing the second number -means that breaking changes were applied. Incrementing the third number implies -backward-compatible features and bug fixes were added. +Versioning of neow3j partially follows an adapted variant of semantic versioning. To be consistent with Neo's major versions, neow3j keeps the first number fixed to the current Neo version. I.e., neow3j 3.x.x for versions of the library that are compatible with Neo N3. The semantics of the version number is therefore shifted to the right by one position. Incrementing the second number means that breaking changes were applied. Incrementing the third number implies backward-compatible features and bug fixes were added. ## Donate 💰 @@ -133,9 +117,7 @@ Help the development of neow3j by donating to the following addresses: | ETH | `0xe85EbabD96943655e2DcaC44d3F21DC75F403B2f` | | BTC | `3L4br7KQ8DCJEZ77nBjJfrukWEdVRXoKiy` | - ## Thanks and Credits 🙏 * [NEO Foundation](https://neo.org/team) & [NEO Global Development (NGD)](https://neo.org/team) -* This project was strongly based on [web3j](https://web3j.io), latest on [this commit](https://github.com/web3j/web3j/commit/2a259ece9736c0338fbb66b1be4c04aba0855254). - We are really thankful for it. 😄 +* This project was strongly based on [web3j](https://web3j.io), latest on [this commit](https://github.com/web3j/web3j/commit/2a259ece9736c0338fbb66b1be4c04aba0855254). We are really thankful for it. 😄 diff --git a/docs/neo-n3/dapp_development/advanced.md b/docs/neo-n3/dapp_development/advanced.md index 0de19f4..53b76cd 100644 --- a/docs/neo-n3/dapp_development/advanced.md +++ b/docs/neo-n3/dapp_development/advanced.md @@ -1,17 +1,9 @@ ## Iterators -**TL;DR** You can use `SmartContract.callFunctionReturningIterator(...)` to invoke a method that returns an iterator and -traverse through the iterator using the resulting `Iterator` object and its utility methods. +**TL;DR:** You can use `SmartContract.callFunctionReturningIterator(...)` to invoke a method that returns an iterator and traverse through the iterator using the resulting `Iterator` object and its utility methods. -A smart contract method can return an iterator that makes it easier to read through storage with many entries. When -calling such a method using an RPC (e.g., `invokefunction`), the node you're connected to opens a session and returns a -`sessionId` and an `iteratorId`. You can then use these values with the RPC `traverseIterator` providing a number `n` of -entries you want to iterate through with each call. When first using this RPC, you will get the first `n` entries of the -iterator. If there are more entries in the iterator, using the same RPC again will return the next `n` entries of the -iterator, etc. +A smart contract method can return an iterator to simplify reading through storage with many entries. When calling such a method using an RPC (e.g., `invokefunction`), the node you're connected to opens a session and returns a `sessionId` and an `iteratorId`. You can then use these values with the RPC `traverseIterator`, specifying the number `n` of entries you want to iterate through with each call. Initially, this RPC returns the first `n` entries of the iterator. If there are more entries, subsequent calls to the same RPC return the next `n` entries of the iterator, and so on. **Note 1:** You cannot traverse an iterator that is returned as the result of a write transaction. -**Note 2:** Some nodes (especially public nodes) have sessions disabled due to DoS concerns. If this is the case, neow3j -provides a custom utility method to unwrap the iterator on the NeoVM level and return an array of entries with the -method `SmartContract.callFunctionAndUnwrapIterator(...)`. \ No newline at end of file +**Note 2:** Some nodes (especially public nodes) have disabled sessions due to DoS concerns. If this is the case, neow3j provides a custom utility method to unwrap the iterator on the NeoVM level and return an array of entries with the method `SmartContract.callFunctionAndUnwrapIterator(...)`. diff --git a/docs/neo-n3/dapp_development/interacting_with_a_node.md b/docs/neo-n3/dapp_development/interacting_with_a_node.md index 00803e0..0c46cf8 100644 --- a/docs/neo-n3/dapp_development/interacting_with_a_node.md +++ b/docs/neo-n3/dapp_development/interacting_with_a_node.md @@ -1,49 +1,36 @@ # Interacting with a Neo Node ## Setting up a Connection -Because neow3j is not a Neo node implementation, interacting with an external node is crucial for any actions that read -from or write to the blockchain. The centerpiece of the interaction with Neo nodes is the `io.neow3j.protocol.Neow3j` -class. It provides Java counterparts for all JSON-RPC methods supported by Neo nodes. + +Since neow3j is not a Neo node implementation, interacting with an external node is crucial for any actions that involve reading from or writing to the blockchain. The primary component for interacting with Neo nodes is the `io.neow3j.protocol.Neow3j` class. This class offers Java equivalents for all JSON-RPC methods supported by Neo nodes. + You can instantiate it as follows: ```java Neow3j neow3j = Neow3j.build(new HttpService("http://localhost:40332")); ``` -This requires a Neo node to be listening at `http://localhost:40332`. Replace that URL with whatever node you want to -connect to. This way of instantiating a `Neow3j` object will set it up with a default configuration. The right -configuration depends on the network you are connecting to. The default values are tailored to the Neo mainnet, e.g., -with a 15 seconds block time. If you are connecting to an other network you might need to adapt the configuration and -instantiate the `Neow3j` object with an instance of `Neow3jConfig`. For example: +This assumes a Neo node is listening at `http://localhost:40332`. Replace that URL with the address of the node you want to connect to. By instantiating a `Neow3j` object in this way, it will be configured with default settings. However, the appropriate configuration depends on the network you are connecting to. The default values are set for the Neo mainnet, including a 15-second block time. If you are connecting to a different network, you may need to customize the configuration and instantiate the `Neow3j` object with an instance of `Neow3jConfig`. For example: ```java -Neow3j neow3j = Neow3j.build(new HttpService("http://localhost:40332"), +Neow3j neow3j = Neow3j.build(new HttpService("http://localhost:40332"), new Neow3jConfig().setNetworkMagic(769)); ``` - -Neow3j uses this configuration internally in a couple of places. E.g., the network magic number is used in the process -of hashing transactions. - -The `Neow3jConfig` has a static member and static methods for setting and getting the address version. It is static -because the address version is required in places where no `Neow3j` instance is available. Make sure that the address -version is matching the addresses you are working with and adjust it with `Neow3jConfig.setAddressVersion(byte version)` -if necessary. - -Now that we have a `Neow3j` instance set up, we can start exploring possible interactions with the Neo blockchain. Most -methods on `Neow3j` construct and return a `Request` object that defines the request and the expected response format. -Call `send()` on that request to actually send it to the Neo node. The returned type will be a subclass of `Response`. -To make sure you don't run into unexpected `NullPointerException`s you can call `hasError()`, `getError()`, or -`throwOnError()` on the response object and handle errors smoothly before trying to access any other response data. - -Another set of methods on `Neow3j` are based on RxJava and return `Observable`s that you can subscribe to. They are -briefly explored in the next section on monitoring the blockchain. + +Neow3j internally utilizes this configuration in several instances. For example, the network magic number is employed in the transaction hashing process. + + +The `Neow3jConfig` class includes a static member and static methods for setting and retrieving the address version. It is designed as static because the address version is needed in contexts where no `Neow3j` instance is accessible. Ensure that the address version matches the type of addresses you are working with, and adjust it using `Neow3jConfig.setAddressVersion(byte version)` if necessary. This ensures compatibility with the specific address format you are interacting with. + +Now that we have set up a `Neow3j` instance, we can begin exploring potential interactions with the Neo blockchain. Most methods on `Neow3j` construct and return a `Request` object that specifies the request and the expected response format. Use `send()` on this request to actually send it to the Neo node. The returned type will be a subclass of `Response`. + +To avoid encountering unexpected `NullPointerException`s, you can use methods like `hasError()`, `getError()`, or `throwOnError()` on the response object to handle errors smoothly before accessing any other response data. These methods help ensure robust error handling when interacting with the Neo blockchain through neow3j. + +Another set of methods available on `Neow3j` are based on [RxJava](https://github.com/ReactiveX/RxJava) and return `Observable`s that you can subscribe to. These methods will be briefly explored in the next section, which covers monitoring the blockchain. This approach enables you to asynchronously observe and react to events and data from the Neo blockchain using neow3j. + ## Monitoring the Blockchain -One common use case in blockchain-related applications is keeping track of new blocks and their contents. There are -several methods on `Neow3j` that allow you to catch up and subscribe to new blocks. Any block retrieved from the Neo -node will be passed on to your subscriber. The following example gets all blocks starting at block index 100 and -subscribes to any newly generated blocks. With the boolean parameter you control if you want to receive the complete -transaction data for each block. +A common use case in blockchain applications involves tracking new blocks and their contents. `Neow3j` offers several methods for catching up and subscribing to new blocks. Any block retrieved from the Neo node will be forwarded to your subscriber. The following example demonstrates fetching all blocks starting from block index 100 and subscribing to newly generated blocks. The boolean parameter controls whether you want to receive complete transaction data for each block. ```java neow3j.catchUpToLatestAndSubscribeToNewBlocksObservable(new BigInteger("100"), true) @@ -55,7 +42,7 @@ neow3j.catchUpToLatestAndSubscribeToNewBlocksObservable(new BigInteger("100"), t }); ``` -Or if you are not interested in any history, start subscribing from the latest block: +If you're not interested in historical blocks and prefer to start subscribing from the latest block: ```java neow3j.subscribeToNewBlocksObservable(true) @@ -69,9 +56,7 @@ neow3j.subscribeToNewBlocksObservable(true) ## Inspecting a transaction -You can retrieve transaction information with the block subscriptions from the last sections but you can also be more -specific and fetch information about single transactions, e.g., if you sent a transaction to a node and now want to -check its state on the blockchain. +You can retrieve transaction information with block subscriptions from the previous sections, but you can also be more specific by fetching information about individual transactions. For example, if you sent a transaction to a node and now want to check its status on the blockchain. ```java Hash256 txHash = new Hash256("da5a53a79ac399e07c6eea366c192a4942fa930d6903ffc10b497f834a538fee"); @@ -82,18 +67,14 @@ if (response.hasError()) { Transaction tx = response.getTransaction(); ``` -This `Transaction` object will contain all the information about the transaction, e.g., the fees paid for it, the block -it was included in, or how many blocks have been added since the transaction was included in a block. If you require the -transaction in its raw byte array form you can use the `getRawTransaction` method instead. It will provide a -Base64-encoded String of the transaction bytes. +The `Transaction` object will contain all the information about the transaction, such as the fees paid for it, the block it was included in, or how many blocks have been added since the transaction was included in a block. If you need the transaction in its raw byte array form, you can use the `getRawTransaction` method instead. This method will provide a Base64-encoded string representing the transaction bytes. ```java NeoGetRawTransaction response = neow.getRawTransaction(txHash).send(); Stribg tx = response.getRawTransaction(); ``` -Most transactions will have an invocation output that is of interest to the dApp. You can get the results of an -invocation with the `getApplicationLog` method. +For most transactions, the invocation output is of interest to the dApp. You can retrieve the results of an invocation using the `getApplicationLog` method. ```java Hash256 txHash = new Hash256("da5a53a79ac399e07c6eea366c192a4942fa930d6903ffc10b497f834a538fee"); @@ -115,27 +96,20 @@ StackItem returnValue = stack.get(0); List notifications = execution.getNotifications(); ``` -The stack included in the application logs will contain all the stack items that the invocation returned. Usually the -return stack is made up of one return value that is at index 0. You will need to know what type of stack item the -invocation returns to be able to interpret it correctly. - -Next to the return value you can also check what notifications have been triggered by the transaction. The applications -log's notifications are one way to track activities of a smart contract. Currently there is no convenient way to follow -a smart contract. You will need to subscribe to new blocks, go through all transaction's application logs, and check if -the logs contain notifications fired by the contract by comparing the contract hash to `notification.getContract()`. +The stack included in the application logs will contain all the stack items returned by the invocation. Typically, the return stack consists of one return value located at index 0. It's important to know the type of stack item that the invocation returns in order to interpret it correctly. +Next to the return value, you can also check for notifications triggered by the transaction. Notifications in the application log provide a way to track activities of a smart contract. Currently, there isn't a straightforward method to monitor a smart contract directly. Instead, you'll need to subscribe to new blocks, inspect transaction application logs, and check for notifications fired by the contract by comparing the contract hash to `notification.getContract()`. ## Using a Wallet on the Node -If you run your own Neo full node you can make use of wallets that are stored directly on that node. Neow3j covers the -necessary methods to interact and make use of such wallets. +If you are running your own Neo full node, you can utilize wallets that are stored directly on that node. Neow3j provides the necessary methods to interact with and use these wallets. -First a wallet needs to be opened. +First, you need to open a wallet: ```java NeoOpenWallet response = neow3j.openWallet("/path/to/wallet.json", "walletPassword").send(); if (response.hasError()) { - throw new Exception("Failed to open walled. Error message: " + response.getError().getMessage()); + throw new Exception("Failed to open wallet. Error message: " + response.getError().getMessage()); } if (response.getOpenWallet()) { @@ -145,7 +119,7 @@ if (response.getOpenWallet()) { } ``` -Now, with the open wallet, you can list the accounts in that wallet. +Once the wallet is open, you can list the accounts in that wallet: ```java NeoListAddress response = neow3j.listAddress().send(); @@ -155,7 +129,7 @@ if (response.hasError()) { List listOfAddresses = response.getAddresses(); ``` -Check the wallets balances. +Check the wallet balances: ```java NeoGetWalletBalance response = neow3j.getWalletBalance(NeoToken.SCRIPT_HASH).send(); @@ -165,23 +139,23 @@ if (response.hasError()) { String balance = response.getWalletBalance().getBalance(); ``` -And, in the end, close the wallet. +Finally, close the wallet: ```java NeoCloseWallet response = neow3j.closeWallet().send(); if (response.hasError()) { - throw new Exception("Failed to close the wallet. Error message: " + response.getError().getMessage()); + throw new Exception("Failed to close the wallet. Error message: " + response.getError().getMessage()); } ``` ## Neo-Express -The class `io.neow3j.protocol.Neow3jExpress` extends the methods of `Neow3j` with methods that are specific to -neo-express. [Neo-express](https://github.com/neo-project/neo-express) is a developer tool that enables a fast workflow. It is basically a tool for managing and configuring private networks for development purposes. -Neo-express exposes several RPC methods additional to normal Neo nodes. These are available through `Neow3jExpress`. Use `Neow3jExpress` just like `Neow3j` but with an URL that points to a neo-express instance. +The class `io.neow3j.protocol.Neow3jExpress` extends the methods of `Neow3j` with methods specific to neo-express. [Neo-express](https://github.com/neo-project/neo-express) is a developer tool that facilitates a streamlined workflow, providing tools for managing and configuring private networks for development purposes. + +Neo-express exposes additional RPC methods compared to normal Neo nodes, accessible through `Neow3jExpress`. Use `Neow3jExpress` similarly to `Neow3j`, but with a URL pointing to a neo-express instance. ```java Neow3jExpress neow3j = Neow3jExpress.build(new HttpService("http://localhost:40332")); ``` -This API is especially of interest to developers that create developer tools using neo-express as the local Neo network. +This API is particularly useful for developers creating tools for neo-express as part of a local Neo network setup. diff --git a/docs/neo-n3/dapp_development/introduction.md b/docs/neo-n3/dapp_development/introduction.md index 3285dcf..923d068 100644 --- a/docs/neo-n3/dapp_development/introduction.md +++ b/docs/neo-n3/dapp_development/introduction.md @@ -1,37 +1,35 @@ # dApp Development -In our definition, dApp development comprises the implementation of systems that interact and are based on a blockchain. -Although, smart contracts are also part of a dApp, we separate contract development and dApp development because -neow3j's libraries are cleanly separable into these two development activities. In this part we introduce the neow3j SDK -which is concerned with dApp development. - -The neow3j SDK attempts to provide a high abstraction layer that relieves the developer from dealing -with technical details of the Neo blockchain. At the same time, it gives the ability for more -detailed configuration for use cases where more control is needed. -You can, for example, use the `NeoToken` class to conveniently construct a NEO transfer -with a single method call, or construct a transaction from scratch using the `TransactionBuilder`. - -The neow3j SDK is divided into two modules `io.neow3j:core` and `io.neow3j:contract` that separate the lower level core -functionalities, like signing, from more abstract functionality, like building contract-specific transactions. The -_core_ module is a dependency of the _contract_ module, so if you add _contract_ as a dependency to your project you -will get the _core_ module as well. - -**`io.neow3j:core`** contains - - Basic definitions and enums. - - Utility methods of which the most notable classes are, e.g., for handling hex strings. - - Cryptographic methods related to key pairs (class `ECKeyPair`) and signatures (class `Sign`). - - Wallet and account management, i.e., the handling of key pairs or reading from and writing to NEP-6 wallet files. - - Interaction with the Neo blockchain, i.e., communication via JSON-RPC with a Neo node. - - The `Transaction` and `ScriptBuilder` classes that are fundamental for constructing contract invocations of any - kind. - -**`io.neow3j:contract`** contains -- Functionality related to smart contracts. -- Classes that allow easy interaction with native contracts. -- Classes that represent and allow easy interaction with contracts following a certain standard, like the NEP-17 token - standard. -- for interfaces like fungible or non-fungible token contracts and native contracts that support building invocation - scripts to create a transaction. - -The following sections explain the SDK's capabilities based on common concepts and activities used in dApp -development. +In our definition, dApp development includes the creation of systems that interact and are based on a blockchain. Although smart contracts are also a component of a dApp, we distinguish between contract development and dApp development because neow3j's libraries cleanly separate these two activities. In this section, we introduce the neow3j SDK, which focuses on dApp development. + +The neow3j SDK aims to offer a high-level abstraction layer that frees developers from handling the technical intricacies of the Neo blockchain. Simultaneously, it provides the capability for more detailed configuration in scenarios requiring greater control. + +For instance, you can utilize the `NeoToken` class to easily create a NEO transfer with a single method call, or build a transaction from the ground up using the `TransactionBuilder`. + +The neow3j SDK is divided into two modules: `io.neow3j:core` and `io.neow3j:contract`. These modules separate lower-level core functionalities, such as signing, from more abstract functionalities, such as building contract-specific transactions. The `core` module is a dependency of the `contract` module. Therefore, if you add `contract` as a dependency to your project, you will automatically include the `core` module as well. + +**`io.neow3j:core`** contains: + +- **Basic definitions and enums**: This includes foundational definitions and enumerations used within the neow3j SDK to establish core concepts and data structures. + +- **Utility methods**: Notable classes here handle tasks such as manipulating hex strings efficiently. + +- **Cryptographic methods**: This involves functionalities related to key pairs (`ECKeyPair` class) and cryptographic signatures (`Sign` class). + +- **Wallet and account management**: The SDK facilitates tasks like managing key pairs, reading from, and writing to NEP-6 wallet files. + +- **Interaction with the Neo blockchain**: This component enables communication with a Neo node via JSON-RPC, facilitating interaction and data exchange with the blockchain. + +- **Transaction and ScriptBuilder classes**: These classes are essential for constructing various types of contract invocations, forming the core functionality for interacting with and executing actions on the Neo blockchain. + +**`io.neow3j:contract`** contains: + +- **Functionality related to smart contracts**: This includes features and utilities specifically designed for working with smart contracts, such as deployment, invocation, and state management. + +- **Classes for easy interaction with native contracts**: These classes provide streamlined methods for interacting with built-in or native contracts on the Neo blockchain. + +- **Classes for standard contract interaction**: This encompasses classes tailored for interacting with contracts that adhere to specific standards, such as the NEP-17 token standard. These classes simplify operations like token transfers and balance inquiries. + +- **Interfaces for token contracts**: The SDK likely includes interfaces for fungible and non-fungible token contracts, enabling developers to interact with these contracts in a standardized manner. Additionally, support for building invocation scripts for transactions involving native contracts would be part of this functionality. + +These sections demonstrate the neow3j SDK's capabilities by highlighting common concepts and activities integral to decentralized application (dApp) development on the Neo blockchain. The SDK aims to streamline and simplify the process of interacting with various types of contracts and blockchain components, empowering developers to focus on application logic and user experience. diff --git a/docs/neo-n3/dapp_development/preliminaries.md b/docs/neo-n3/dapp_development/preliminaries.md index 55e0c4a..33da9db 100644 --- a/docs/neo-n3/dapp_development/preliminaries.md +++ b/docs/neo-n3/dapp_development/preliminaries.md @@ -1,35 +1,18 @@ # Preliminaries -The following sections introduce general concepts and types that you will meet throughout the neow3j SDK. +The following sections introduce general concepts and types that you will encounter within the neow3j SDK. + ## Hashes -Hashes appear a lot in the blockchain world and Neo is not an exception. There are two kinds of hashes in Neo. One -is 256 bit long and produced by applying the SHA-256 (member of the SHA-2 cryptographic hash functions) twice to some -input data. It is used for transaction and block hashes. The other is 160 bit long and produced by first applying -SHA-256 and then RIPEMD-160 to some input data. It is used for identifying accounts and contracts in the form of script -hashes, i.e., hashes of the scripts underlying those accounts and contracts. +Hashes are frequently used in the blockchain world, and Neo is no exception. There are two types of hashes in Neo: -The neow3j SDK uses the types `io.neow3j.contract.Hash256` and `io.neow3j.contract.Hash160` for those two hash types, -respectively. You will see that the SDK's API almost always requires you to work with these two types instead of a -simple string or byte array. Note, that the hashes stored by these types are stored in big-endian order but can be -retrieved in little-endian order via the `toLittleEndianArray()` method. Endianness might be an issue when inspecting -results from contract invocations, because the Neo node might return a hash in little-endian order, which you have to be -aware of when constructing a `Hash160` or `Hash256`. +- One is 256 bits long and is generated by applying the SHA-256 algorithm (a member of the SHA-2 cryptographic hash functions) twice to certain input data. This type of hash is used for transaction and block hashes. +- The other type is 160 bits long and is generated by first applying SHA-256 and then RIPEMD-160 to specific input data. This hash type is used for identifying accounts and contracts in the form of script hashes, which are hashes of the scripts associated with those accounts and contracts. +The neow3j SDK uses the types `io.neow3j.contract.Hash256` and `io.neow3j.contract.Hash160` for these two types of hashes, respectively. You will find that the SDK's API typically requires you to work with these specific types rather than a simple string or byte array. It's important to note that the hashes stored by these types are stored in big-endian order, but they can be retrieved in little-endian order using the `toLittleEndianArray()` method. [Endianness](https://en.wikipedia.org/wiki/Endianness) can be a concern when inspecting results from contract invocations because the Neo node might return a hash in little-endian order. This difference in endianness must be taken into account when constructing a `Hash160` or `Hash256` object. ## NeoVM Stack Items -The NeoVM is the virtual machine on which all smart contract code is executed. When invoking a contract on the -Neo blockchain, the result of that invocation is a list of items that are left on the NeoVM's stack at the end of the - invocation. These items are called stack items and are represented by the `StackItem` class in neow3j SDK. Stack items -can be one of several defined types that exist on the NeoVM and they have to be mapped into Java types when the SDK -receives them from a Neo node. This mapping is not a simple one-to-one mapping but leaves space for more interpretation. -For example, a stack item containing an integer can be interpreted as a boolean value if it is in the range of 0 and 1. -Or a byte array can be interpreted as an integer value. - -The `StackItem` class in neow3j lets you choose to which Java type you want to "cast" a stack item. Any stack item that -is returned by a Neo node will be wrapped into the `StackItem` class. Then, if you know that an invocation is returning -a boolean value you can call `stackItem.getBoolean()` and you will receive true or false even if the stack item is an -integer of value 0 or 1 behind the scenes. If the stack item is not castable to the type you desire, an exception will -be thrown. E.g., if you call `stackItem.getMap()` on an integer stack item, it will not give you a map-interpretation of -that integer but simply throw an exception. Thus, you still need to know what type of stack item an invocation will return. +The NeoVM is the virtual machine responsible for executing all smart contract code on the Neo blockchain. When a contract is invoked on the Neo blockchain, the result of that invocation is a list of items that remain on the NeoVM's stack at the end of the invocation. These items are referred to as stack items and are represented by the `StackItem` class in the neow3j SDK. Stack items can belong to several predefined types that exist within the NeoVM, and they need to be mapped to Java types when received by the SDK from a Neo node. This mapping isn't a straightforward one-to-one translation but allows room for interpretation. For instance, an integer stack item can be interpreted as a boolean value if it falls within the range of 0 and 1. Similarly, a byte array can be interpreted as an integer value. + +The `StackItem` class in neow3j allows you to specify the Java type to which you want to convert a stack item. Any stack item returned by a Neo node will be encapsulated within the `StackItem` class. If you are expecting a boolean value from an invocation, you can use `stackItem.getBoolean()` to retrieve `true` or `false`, even if the underlying stack item is an integer with a value of 0 or 1. However, if the stack item cannot be cast to the desired type, an exception will be thrown. For example, calling `stackItem.getMap()` on an integer stack item will not interpret the integer as a map; instead, it will throw an exception. Therefore, it's important to know beforehand what type of stack item an invocation will return to handle it appropriately in your code. diff --git a/docs/neo-n3/dapp_development/smart_contracts.md b/docs/neo-n3/dapp_development/smart_contracts.md index 0cf279b..88c11af 100644 --- a/docs/neo-n3/dapp_development/smart_contracts.md +++ b/docs/neo-n3/dapp_development/smart_contracts.md @@ -1,15 +1,8 @@ # Smart Contracts -To deploy, invoke or just retrieve information about any contract's state on the blockchain, the class `SmartContract` -can be used. It is the most generic class in the neow3j SDK that models a contract. All other contract classes are -subclasses of this one. On one hand, `SmartContract` offers methods to invoke a contract on the blockchain with the -result of an actual state change. On the other hand, you can use it to simulate an invocation without actually inducing -state changes. The latter is also used when the invocation only performs read actions. +To deploy, invoke, or retrieve information about any contract's state on the blockchain, you can use the `SmartContract` class. It is the most general class in the neow3j SDK that models a contract. All other contract classes are subclasses of this one. On one hand, `SmartContract` offers methods to invoke a contract on the blockchain resulting in an actual state change. On the other hand, you can use it to simulate an invocation without actually changing the state. The latter is also used when the invocation only performs read actions. -The only method that creates an actual transaction is `invokeFunction(...)`. It builds a script based on the provided -function name and contract parameters and constructs a `TransactionBuilder` with it. The returned transaction builder -can then be configured, built, and the transaction send as described in the Section -[Transactions](neo-n3/dapp_development/transactions.md). This process is visualized in the following figure. +The only method that creates an actual transaction is `invokeFunction(...)`. It builds a script based on the provided function name and contract parameters and constructs a `TransactionBuilder` with it. The returned transaction builder can then be configured, built, and the transaction sent as described in the [Transactions](neo-n3/dapp_development/transactions.md) section. This process is visualized in the following figure. ``` Build script -> Configure transaction -> Tx ready to sign and send @@ -19,28 +12,15 @@ can then be configured, built, and the transaction send as described in the Sect --------------- -------------------- ------------- ``` +The methods that don't change blockchain state all start with the word "call" to indicate that the performed invocation is only a call to the Neo JSON-RPC API's `invokefunction` or `invokescript` methods. They don't produce transaction builders or transactions. There are several of such "call" methods, with the basic one being `callInvokeFunction(...)`. If you know what type the contract invocation will return, you can use one of the more specific call methods that already unpack the invocation result value, e.g., `callFunctionReturningScriptHash(...)`. -The methods that don't change blockchain state all start with the word *call* to indicate that the performed invocation -is only a call to the Neo JSON-RPC API's `invokefunction` or `invokescript` methods. They don't produce transaction -builders or transactions. There are several of such *call* methods, with the basic one being `callInvokeFunction(...)`. -If you know what type the contract invocation will return, you can use one of the more specific call methods that -already unpack the invocation result value, e.g., `callFunctionReturningScriptHash(...)`. - -Conversely to the return type, each method of a contract takes specific parameter types as input. In order to know what -methods exist in a smart contract, and what parameter types it requires, every contract has a manifest that provides you -with this and much more information about the contract. In the following sections, we'll show you how to create contract -parameters, get the manifest and figure out what parameters you need to pass to a function you want to invoke. +Contrary to the return type, each method of a contract takes specific parameter types as input. To know what methods exist in a smart contract and what parameter types it requires, every contract has a manifest that provides you with this and much more information about the contract. In the following sections, we'll show you how to create contract parameters, get the manifest, and figure out what parameters you need to pass to a function you want to invoke. ## Contract Parameters -When invoking a smart contract, you will need parameters. The neow3j SDK represents parameters via the -`ContractParameter` class. It provides many static construction methods that cover all possible parameter types. If you -use those methods, neow3j will make sure that the parameter is sent to the contract in the correct encoding and the -correct type declaration. For example, if you need to pass a script hash of a NEO address as a parameter, you can use -the method `ContractParameter.hash160(...)`. It converts the script hash to the expected byte array. +When invoking a smart contract, you will need parameters. The neow3j SDK represents parameters via the `ContractParameter` class. It provides many static construction methods that cover all possible parameter types. If you use those methods, neow3j will make sure that the parameter is sent to the contract in the correct encoding and the correct type declaration. For example, if you need to pass a script hash of a NEO address as a parameter, you can use the method `ContractParameter.hash160(...)`. It converts the script hash to the expected byte array. -If you invoke a contract that takes an object as a parameter, you need to use a contract parameter of type `Array`. As -an example, assume the that the `Bongo` struct class below is the expected method parameter. +If you invoke a contract that takes an object as a parameter, you need to use a contract parameter of type `Array`. As an example, assume that the `Bongo` struct class below is the expected method parameter. ```java @Struct @@ -56,39 +36,33 @@ public class Bongo { } ``` -Using the neow3j SDK, you would have to construct the following parameter representing a `Bongo` instance. +Using the neow3j SDK, you would need to construct the following parameter to represent a `Bongo` instance. ```java ContractParameter.array( - ContractParameter.string("C2"), - ContractParameter.string("C5"))); + ContractParameter.string("C2"), + ContractParameter.string("C5")); ``` -The same applies when the object is used in a return type. In other words, expect a return value of type `Array` that -will hold the object's variables in the order they appear in the class. - +The same concept applies when the object is used in a return type. In other words, expect a return value of type `Array` that holds the object's variables in the order they appear in the class. ## Contract Invocation -First, you have to specify which contract and which function you want to invoke. Use the `io.neow3j.contract.Hash160` -class for the contract's script hash and create a `SmartContract` together with a `Neow3j` instance. +First, specify which contract and which function you want to invoke. Use the `io.neow3j.contract.Hash160` +class for the contract's script hash and create a `SmartContract` along with a `Neow3j` instance. ```java Hash160 scriptHash = new Hash160("0x1a70eac53f5882e40dd90f55463cce31a9f72cd4"); SmartContract smartContract = new SmartContract(scriptHash, neow3j); ``` -Then, you need to define the parameters that will be passed to the contract. In order to know what parameters you need -to pass to the contract, you need information about its methods. You can get that information by reading the contract's -ABI that's in the manifest. In the following it's shown how you can get all the methods of a smart contract with their -names, parameters, and return type in order to know what parameters you need to pass to a function and also what you -can expect to be returned. +Then, define the parameters that will be passed to the contract. To determine the required parameters, you need information about its methods. You can obtain this information by reading the contract's ABI in the manifest. The following example shows how to retrieve all methods of a smart contract with their names, parameters, and return type to understand what parameters are needed for a function and what you can expect to be returned: ```java List methods = smartContract.getManifest().getAbi().getMethods(); ``` -In this example, we are invoking a name service contract and call the `register` function with a domain name and an +In this example, we are invoking a name service contract and calling the `register` function with a domain name and an address that should be registered under that domain name. ```java @@ -98,7 +72,7 @@ ContractParameter accountParam = ContractParameter.hash160(account.getScriptHash ``` With the smart contract instance, the function, and the parameters, we can construct an invocation as follows. This -doesn't yet send a transaction but it builds the correct script and instantiates a transaction builder with it for +does not yet send a transaction, but it builds the correct script and instantiates a transaction builder with it for further configuration. ```java @@ -126,8 +100,7 @@ NeoSendRawTransaction response = new SmartContract(scriptHash, neow3j) .send(); ``` -Of course, it is also possible to call a smart contract function that doesn't take any parameters, e.g., a contract that -simply increments a number every time it gets called. +Of course, it is also possible to call a smart contract function that doesn't take any parameters, for example, a contract that simply increments a number every time it gets called. ```java NeoSendRawTransaction response = new SmartContract(contract, neow3j) @@ -139,12 +112,7 @@ NeoSendRawTransaction response = new SmartContract(contract, neow3j) ## Testing the Invocation -If you need to know the effect of your invocation before actually propagating it through the network, you can do a test -invocation first. This also calls the RPC node but only simulates the execution without any effects on the blockchain. -Continuing the above example of the domain name contract, a test invocation would look like the following. Notice that -depending on what call you perform, you also need to add signers even though no blockchain state is changed. In this -specific example the signer is needed because in the called contract it will be verified if the account that is -registered is also the sender of the transaction. +If you need to know the effect of your invocation before actually propagating it through the network, you can do a test invocation first. This also calls the RPC node but only simulates the execution without any effects on the blockchain. Continuing the above example of the domain name contract, a test invocation would look like the following. Notice that depending on what call you perform, you also need to add signers even though no blockchain state is changed. In this specific example, the signer is needed because the called contract will verify if the account that is registered is also the sender of the transaction. ```java Neow3j neow3j = Neow3j.build(new HttpService("http://localhost:40332")); @@ -158,26 +126,18 @@ ContractParameter accountParam = ContractParameter.hash160(account.getScriptHash List params = Arrays.asList(domainParam, accountParam); NeoInvokeFunction response = new SmartContract(scriptHash, neow3j) - .callInvokeFunction(funtion, params, AccountSigner.calledByEntry(account)); + .callInvokeFunction(function, params, AccountSigner.calledByEntry(account)); ``` -The `NeoInvokeFunction` holds information about the GAS amount consumed in the contract execution, the VM exit state -(e.g. HALT or FAULT), and the VM's stack, i.e. the return value. +The `NeoInvokeFunction` holds information about the GAS amount consumed in the contract execution, the VM exit state (e.g., HALT or FAULT), and the VM's stack, i.e., the return value. ## Contract Interfaces -There are several subclasses of `SmartContract` that implement a sort of interface to Neo's native contracts and -contracts that follow token standards. Here, the word interface means that these classes provide an interface to -interact with the deployed contracts. Token contracts are discussed separately in Section [Token -Contracts](neo-n3/dapp_development/token_contracts.md). They include fungible and non-fungible tokens such as `NeoToken` -and `GasToken`. The other available contract classes are discussed below. +There are several subclasses of `SmartContract` that implement a type of interface to Neo's native contracts and contracts that follow token standards. Here, the term "interface" means that these classes provide a way to interact with the deployed contracts. Token contracts, including fungible and non-fungible tokens such as `NeoToken` and `GasToken`, are discussed separately in Section [Token Contracts](neo-n3/dapp_development/token_contracts.md). The other available contract classes are discussed below. ### ContractManagement -The `ContractManagement` contract is a Neo native contract that, as its name suggests, can be used to manage other -contracts. More precisely, it allows you to deploy, update, and delete a contract. In the neow3j SDK the update and -delete methods cannot be used, because they can only be called from within another contract. But, the deploy method is -available and allows you to deploy new contracts with neow3j. For example: +The `ContractManagement` contract is a native Neo contract that, as its name suggests, can be used to manage other contracts. More specifically, it allows you to deploy, update, and delete a contract. In the neow3j SDK, the update and delete methods cannot be used because they can only be called from within another contract. However, the deploy method is available and allows you to deploy new contracts with neow3j. For example: ```java Transaction tx = new ContractManagement(neow3j) @@ -186,39 +146,24 @@ Transaction tx = new ContractManagement(neow3j) .sign(); ``` -Producing the necessary NEF (Neo Executable Format) file and contract manifest is not discussed here but are part of -the Contract Development [section](). - -There are two other methods on `ContracManagement`. They are concerned with the minimum deployment fee. The getter -`getMinimumDeploymentFee()` can be used by anyone. But, the setter `setMinimumDeploymentFee(...)` can only successfully -be used if the transaction is signed by committee members. I.e., it will be of no use to most developers. +Producing the necessary NEF (Neo Executable Format) file and contract manifest is not discussed here but are part of the Contract Development [section](). +There are two other methods on `ContractManagement`. They are concerned with the minimum deployment fee. The getter `getMinimumDeploymentFee()` can be used by anyone. However, the setter `setMinimumDeploymentFee(...)` can only successfully be used if the transaction is signed by committee members, meaning it will be of no use to most developers. ### PolicyContract -The `PolicyContract` holds information about several settings of the Neo network. You can retrieve information like GAS -fee per transaction byte, the GAS price per byte of contract storage, or if a certain account is blacklisted. - -The contract also provides setters for all of these values, though, these can only successfully be used if the -transaction is signed by committee members. +The `PolicyContract` holds information about several settings of the Neo network. You can retrieve information like GAS fee per transaction byte, the GAS price per byte of contract storage, or if a certain account is blacklisted. +The contract also provides setters for all of these values, though they can only successfully be used if the transaction is signed by committee members. ### RoleManagement -The `RoleManagament` contract is used to assign roles to nodes in the network. A node can be a state validator, an -oracle node, or a NeoFS "Alphabet" node (responsible for consensus on NeoFS sidechain). - -The designation of a node to a role can only be done via the Neo committee. But you can check the role assignments with -the `getDesignatedRole(...)` method. +The `RoleManagement` contract is used to assign roles to nodes in the network. A node can be a state validator, an oracle node, or a NeoFS "Alphabet" node (responsible for consensus on NeoFS sidechain). +The designation of a node to a role can only be done via the Neo committee. However, you can check the role assignments with the `getDesignatedRole(...)` method. ### NeoNameService -The `NeoNameService` is not a native contract but managed by the Neo core team. The script hash of this contract is not -known to neow3j and has to be provided by the developer when constructing an instance of `NeoNameService`. As its name -suggest the name service contract provides the possibility to map a name to an owner account. You can read more about it -in the official [Neo Docs](https://docs.neo.org/docs/en-us/reference/nns.html). +The `NeoNameService` is not a native contract but managed by the Neo core team. The script hash of this contract is not known to neow3j and has to be provided by the developer when constructing an instance of `NeoNameService`. As its name suggests, the name service contract provides the possibility to map a name to an owner account. You can read more about it in the official [Neo Docs](https://docs.neo.org/docs/n3/Advances/neons/index.html). -The `NeoNameService` class in the neow3j SDK provides you with all the methods of the contract. So you can check -registered names and register your own name-to-address mappings. Some of them can only be called by the Neo committee, -e.g., `addRoot(...)` or `setPrice(...)` methods. +The `NeoNameService` class in the neow3j SDK provides you with all the methods of the contract. So you can check registered names and register your own name-to-address mappings. Some of them can only be called by the Neo committee, for example, `addRoot(...)` or `setPrice(...)` methods. diff --git a/docs/neo-n3/dapp_development/token_contracts.md b/docs/neo-n3/dapp_development/token_contracts.md index b484ecd..1264898 100644 --- a/docs/neo-n3/dapp_development/token_contracts.md +++ b/docs/neo-n3/dapp_development/token_contracts.md @@ -1,16 +1,8 @@ # Token Contracts -There are two token standards on Neo, one for fungible and one for non-fungible tokens. The neow3j SDK covers the -interaction with such token contracts in the classes `FungibleToken` and `NonFungibleToken`. - -The following graph shows how the classes around token contracts are structured. They are sub-types of the -`SmartContract` base class and add all token contract specific methods ontop. -In the subtype `Token` the common methods used in token contracts like `getDecimals()`, `getSymbol()` or -`getTotalSupply()` are collected. In the subtype `FungibleToken` the NEP-17 standard is implemented. Two specific -instances of NEP-17 contracts are the native contracts `NeoToken` and `GasToken`. They contain their additional methods -that are specific to them, e.g., `registerValidator`, `getRegisteredValidators` or `vote`. The `NonFungibleToken` -represents a wrapper for token contracts that comply with the NEP-11 standard for non-fungible tokens. The -`NeoNameService` contract is a specific example for such a contract. +There are two token standards on Neo: one for fungible and one for non-fungible tokens. The neow3j SDK covers the interaction with such token contracts through the classes `FungibleToken` and `NonFungibleToken`. + +The following graph illustrates the structure of the classes related to token contracts. They are subtypes of the `SmartContract` base class and provide specific token contract methods. In the `Token` subtype, common methods used in token contracts like `getDecimals()`, `getSymbol()`, or `getTotalSupply()` are collected. The `FungibleToken` subtype implements the NEP-17 standard. Two specific instances of NEP-17 contracts are the native contracts `NeoToken` and `GasToken`, which contain additional methods specific to them, such as `registerValidator`, `getRegisteredValidators`, or `vote`. The `NonFungibleToken` represents a wrapper for token contracts that comply with the NEP-11 standard for non-fungible tokens. The `NeoNameService` contract is a specific example of such a contract. ``` Build invocation script -> Specify Tx Signers, etc. -> Tx ready to sign and send @@ -20,9 +12,9 @@ represents a wrapper for token contracts that comply with the NEP-11 standard fo | ------- | Token | - ------- -------------------- ------------- - / \ -> | TransactionBuilder | -> | Transaction | - --------------- ------------------ -------------------- ------------- + ------- -------------------- ------------- + / \ -> | TransactionBuilder | -> | Transaction | + --------------- ------------------ -------------------- ------------- | FungibleToken | | NonFungibleToken | --------------- ------------------ / \ \ @@ -31,18 +23,11 @@ represents a wrapper for token contracts that comply with the NEP-11 standard fo ---------- ---------- ---------------- ``` -All of these classes provide methods to build scripts and a transactions for contract invocation. The methods that -change state return a `TransactionBuilder` that can be used to further configure the transaction, e.g., specify signers -or an additional network fee. The transaction can then be signed and built, and the returned `Transaction` sent to a Neo -node. +All of these classes provide methods to build scripts and transactions for contract invocation. The methods that change state return a `TransactionBuilder` that can be used to further configure the transaction, such as specifying signers or an additional network fee. The transaction can then be signed and built, and the resulting `Transaction` can be sent to a Neo node. ## Fungible Token Contracts (NEP-17) -The most prominent method on [NEP-17](https://github.com/neo-project/proposals/blob/master/nep-17.mediawiki) token -contracts is the `transfer` method. There are a couple of overloads for this method. In its basic form `transfer` takes -an `Account` as the for the sender. That account is added as a signer to the transaction builder with witness scope -`calledByEntry` . If the account contains a private key, you can use `sign()` to automatically sign the resulting -transaction. +The most prominent method on [NEP-17](https://github.com/neo-project/proposals/blob/master/nep-17.mediawiki) token contracts is the `transfer` method. There are several overloads for this method. In its basic form, `transfer` takes an `Account` as the sender. That account is added as a signer to the transaction builder with a witness scope of `calledByEntry`. If the account contains a private key, you can use `sign()` to automatically sign the resulting transaction. ```java Account account = Account.fromWIF("L3kCZj6QbFPwbsVhxnB8nUERDy4mhCSrWJew4u5Qh5QmGMfnCTda"); @@ -54,14 +39,12 @@ NeoSendRawTransaction response = new NeoToken(neow3j) .send(); ``` -Another `transfer` method allows you to pass a `Hash160` instead of `Account` for the sender. In this version, no signer -is attached and it is up to you to add the correct signer. This is useful when the sender is a contract as in the -example below. +Another `transfer` method allows you to pass a `Hash160` instead of an `Account` for the sender. In this version, no signer is attached, and it is up to you to add the correct signer. This is useful when the sender is a contract, as in the example below. ```java -Hash160 contractHash = new Hash160("0xacce6fd80d44e1796aa0c2c625e9e4e0ce39efc0") +Hash160 contractHash = new Hash160("0xacce6fd80d44e1796aa0c2c625e9e4e0ce39efc0"); Hash160 to = Hash160.fromAddress("NWcx4EfYdfqn5jNjDz8AHE6hWtWdUGDdmy"); -// Owner of the contract. Required in for verifying the withdraw from the contract. +// Owner of the contract. Required for verifying the withdrawal from the contract. Account account = Account.fromWIF("L3kCZj6QbFPwbsVhxnB8nUERDy4mhCSrWJew4u5Qh5QmGMfnCTda"); NeoSendRawTransaction response = new NeoToken(neow3j) @@ -72,38 +55,21 @@ NeoSendRawTransaction response = new NeoToken(neow3j) .send(); ``` -In both variations of the `transfer` method, there is another overload that allows you to pass a contract parameter. -That parameter is forwarded to the `onNep17Payment` method if the receiver is a smart contract and has implemented that -method. If you want to pass multiple parameters you need to do it inside a `ContractParameter.array(...)`. +In both variations of the `transfer` method, there is another overload that allows you to pass a contract parameter. That parameter is forwarded to the `onNep17Payment` method if the receiver is a smart contract and has implemented that method. If you want to pass multiple parameters, you need to do it inside a `ContractParameter.array(...)`. ## Non-fungible Token Contracts (NEP-11) -The wrapper class `NonFungibleToken` provides support for the -[NEP-11](https://github.com/neo-project/proposals/blob/master/nep-11.mediawiki) standard. Take a look at the standard -for detailed information about non-fungible tokens on the Neo blockchain. +The wrapper class `NonFungibleToken` provides support for the [NEP-11](https://github.com/neo-project/proposals/blob/master/nep-11.mediawiki) standard. Refer to the standard for detailed information about non-fungible tokens on the Neo blockchain. -It is important to understand that the standard supports non-divisible as well as divisible non-fungible tokens. -For divisible tokens, a token can have multiple owners. Each owner owns a fraction of that token. -The provided wrapper class supports both divisible and non-divisible tokens, while methods that are only intended -for divisible tokens are not allowed to be used for non-divisible tokens, vice-versa. +It is important to understand that the standard supports both non-divisible and divisible non-fungible tokens. For divisible tokens, a token can have multiple owners, where each owner owns a fraction of that token. The provided wrapper class supports both divisible and non-divisible tokens, while methods that are only intended for divisible tokens cannot be used for non-divisible tokens, and vice versa. -Both divisible and non-divisible token contracts implement the method `balanceOf(owner)`. It simply returns the number -of tokens owned by the given address. On divisible tokens this includes fractional amounts of tokens. To get the -fractional amount owned of a specific token, you can use the method `balanceOf(owner, tokenId)` that is specifically -implemented by divisible tokens. +Both divisible and non-divisible token contracts implement the method `balanceOf(owner)`, which simply returns the number of tokens owned by the given address. For divisible tokens, this includes fractional amounts of tokens. To get the fractional amount owned of a specific token, you can use the method `balanceOf(owner, tokenId)`, specifically implemented by divisible tokens. -Further, NFTs provide the methods `tokens`, `tokensOf` and `ownerOf`. The method `ownerOf` returns the single owner of a -non-divisible token. With divisible tokens, this method returns an iterator with all owners that own a share of this token. +Furthermore, NFTs provide methods like `tokens`, `tokensOf`, and `ownerOf`. The method `ownerOf` returns the single owner of a non-divisible token. With divisible tokens, this method returns an iterator with all owners that own a share of this token. -Then, there are multiple overloads for the `transfer` methods, some for non-divisible and some for divisible tokens that -are both. For divisible tokens the method has an additional parameter for the fractional token amount to transfer. -Similar to the overloads on the `FungibleToken` class (see previous section), `NonFungibleToken` also provides further -overloads for the sender address to be either an `Account` or `Hash160`, and for adding a contract parameter that is -passed to the `onNep11Payment` method if the receiver is a smart contract. +There are multiple overloads for the `transfer` method, some for non-divisible tokens and some for divisible tokens. For divisible tokens, the method has an additional parameter for the fractional token amount to transfer. Similar to the overloads on the `FungibleToken` class (see previous section), `NonFungibleToken` also provides further overloads for the sender address, either an `Account` or `Hash160`, and for adding a contract parameter passed to the `onNep11Payment` method if the receiver is a smart contract. -Here's an example for sending 200 fractions of the token with ID 1. The fractional amount has to be in accordance with -the number of decimals the token can have. You can fetch the number of decimals via the `getDecimals()` method or -calculate the amount via the `toFractions(...)` method. +Here's an example of sending 200 fractions of the token with ID 1. The fractional amount must be in accordance with the number of decimals the token can have. You can fetch the number of decimals via the `getDecimals()` method or calculate the amount via the `toFractions(...)` method. ```java Account account = Account.fromWIF("L3kCZj6QbFPwbsVhxnB8nUERDy4mhCSrWJew4u5Qh5QmGMfnCTda"); @@ -113,7 +79,7 @@ NonFungibleToken nft = new NonFungibleToken(new Hash160("ebc856327332bcffb7587a2 TransactionBuilder builder = nft.transfer(account, to, new BigInteger("200"), new byte[]{1}); ``` -The NEP-11 has an optional method `properties` that returns the properties of a token. You can get a tokens properties as shown below. +The NEP-11 standard includes an optional method `properties` that returns the properties of a token. You can retrieve a token's properties as shown below. ```java NFTokenState properties = nft.properties(new byte[]{1}); diff --git a/docs/neo-n3/dapp_development/transactions.md b/docs/neo-n3/dapp_development/transactions.md index f423c11..1b3b94e 100644 --- a/docs/neo-n3/dapp_development/transactions.md +++ b/docs/neo-n3/dapp_development/transactions.md @@ -1,87 +1,52 @@ # Transactions -Transactions are the main protagonists when changing blockchain state. Every change is induced by a transaction. Neo's -transactions are very generic. There are no transaction types. What determines their impact is the attached script. A -script is a sequence of NeoVM instructions and can therefore take many forms, though, transaction scripts usually -contain one or more calls to smart contracts. The full definition of a Neo transaction is described -[here](https://docs.neo.org/docs/en-us/basic/concept/transaction.html) in the official Neo documentation. +Transactions are essential for changing the blockchain state. Every change is initiated by a transaction. Neo's transactions are quite generic; they do not have specific types. Instead, their impact is determined by the attached script. A script is a sequence of NeoVM instructions and can therefore take various forms, although transaction scripts usually involve one or more calls to smart contracts. You can find the complete definition of a Neo transaction described [here](https://docs.neo.org/docs/n3/foundation/Transactions.html) in the official Neo documentation. -The neow3j SDK represents Neo transactions in its `io.neow3j.transaction.Transaction` class. It provides all necessary -functionality to serialize to a byte array and send the transaction to a Neo node. But, constructing a valid transaction -manually would be a tedious task. Therefore, neow3j provides the `io.neow3j.contract.TransactionBuilder`, which takes -care of building a valid transaction and points out wrong configurations as early as possible. +The neow3j SDK represents Neo transactions in its `io.neow3j.transaction.Transaction` class. It provides all the necessary functionality to serialize into a byte array and send the transaction to a Neo node. However, constructing a valid transaction manually would be a tedious task. Therefore, neow3j provides the `io.neow3j.contract.TransactionBuilder`, which simplifies the process of building a valid transaction and identifies incorrect configurations as early as possible. ## Building Transactions -The `TransactionBuilder` and the `Transaction` require a connection to a Neo node for fetching information, like fees -or to send the transaction. Therefore, the `TransactionBuilder` is instantiated with a `Neow3j` object. Once -constructed, the builder allows you to set almost all the properties a Neo transaction can have. The system fee, which -is the amount of GAS your transaction will consume, and the network fee, which is based on the size of your transaction -and the efforts to verify it, are both fetched automatically when building the transaction. +The `TransactionBuilder` and the `Transaction` require a connection to a Neo node to fetch information such as fees or to send the transaction. Therefore, the `TransactionBuilder` is instantiated with a `Neow3j` object. Once constructed, the builder allows you to set almost all the properties a Neo transaction can have. The system fee, which is the amount of GAS your transaction will consume, and the network fee, which is based on the size of your transaction and the effort required to verify it, are both fetched automatically when building the transaction. ```java Neow3j neow3j = Neow3j.build(new HttpService("http://127.0.0.1:40332")); TransactionBuilder builder = new TransactionBuilder(neow3j); ``` -The properties called *nonce*, *validUntilBlock*, and *version* will also be set automatically if not set explicitly. -The *nonce* prevents replay attacks in which the exact same transaction is copied and sent again. Its default value is -set at random by the transaction builder. The *validUntilBlock* value determines for how long the transaction will -remain valid before it is included in a block. If it does not get included before that time, it will be discarded by -the network. The default value is set as the maximum supported by the connected network. The transaction *version* is -set to 0 by default which you will most probably not have to change. +The properties called _nonce_, _validUntilBlock_, and _version_ will also be set automatically if not set explicitly. The _nonce_ prevents replay attacks, where the exact same transaction is copied and sent again. Its default value is set randomly by the transaction builder. The _validUntilBlock_ value determines how long the transaction will remain valid before it needs to be included in a block. If it is not included before that time, it will be discarded by the network. The default value is set as the maximum supported by the connected network. The transaction _version_ is set to 0 by default, which you will most probably not need to change. -The properties that are of most interest are the transaction's script and its signers. As mentioned before, the script -determines the actual effects of the transaction on the blockchain state. How to build the script itself is not -discussed here. Neow3j offers many classes in the `contract` module that will provide you with a `TransactionBuilder` -holding a preconfigured script. +The properties of most interest are the transaction's script and its signers. As mentioned earlier, the script determines the actual effects of the transaction on the blockchain state. The process of building the script itself is not discussed here. Neow3j offers many classes in the `contract` module that will provide you with a `TransactionBuilder` holding a preconfigured script. ```java builder.script(script); ``` -The use of transaction signers is twofold. The first signer in the list specifies the account that will pay for the -transaction fees - it is called the `sender` of the transaction. Secondly, all signers - including the first in the -list - are used to allow specific actions of the script that are depending on the signature of an account. For example, -if a token should be transferred from account a to account b, usually this requires the approval of account a. +The usage of transaction signers serves a dual purpose. The first signer in the list specifies the account that will pay for the transaction fees, known as the `sender` of the transaction. Additionally, all signers, including the first one in the list, are used to authorize specific actions within the script that depend on the signature of an account. For example, transferring a token from account A to account B typically requires approval from account A. -You can set the signers of a transaction with the method `signers(Signer... signers)` in the transaction builder. Note, -that the first signer in the provided parameters is used as the transaction's sender. In case you have set all signers, -but want to change the sender to another signer, you can use the method `firstSigner(Hash160 account)` to set it -explicitly. +You can set the signers of a transaction using the `signers(Signer... signers)` method in the transaction builder. Note that the first signer provided in the parameters will be used as the transaction's sender. If you have specified all the signers but want to change the sender to another signer, you can use the `firstSigner(Hash160 account)` method to set it explicitly. ```java +// Import the Account class from the io.neow3j.wallet package +import io.neow3j.wallet.Account; + +// Instantiate the Account class as follows Account account = Account.fromWIF("L24Qst64zASL2aLEKdJtRLnbnTbqpcRNWkWJ3yhDh2CLUtLdwYK2"); builder.signers(AccountSigner.calledByEntry(account)); ``` -Signers are associated with a witness scope that restricts how the signer's witness* can be used in an invocation. -For example, if a signer is only needed for paying the transaction fee, the witness scope can be set to *None*. There -are two signer classes to be aware of - the `AccountSigner` and the `ContractSigner`. Use `AccountSigner` for signers -that are backed by an account. It provides static builder methods for all witness scopes. +Signers are associated with a witness scope that restricts how the signer's witness* can be used during invocation. For instance, if a signer is only needed for paying the transaction fee, the witness scope can be set to *None\*. There are two signer classes to be aware of - `AccountSigner` and `ContractSigner`. Use `AccountSigner` for signers backed by an account, which provides static builder methods for all witness scopes. -Use `ContractSigner` if the signer is a smart contract. This kind of signer doesn't require a signature, but will call -the contract's `verify(...)` method when the transaction is executed. Since contract signers cannot pay the transaction -fees, the class `ContractSigner` does not provide a builder method for the *None* witness scope. Further, the -`ContractSigner`'s builder methods can take contract parameters in case the contract's `verify(...)` method has extra -parameters. +Use `ContractSigner` if the signer is a smart contract. This type of signer does not require a signature but calls the contract's `verify(...)` method during transaction execution. Since contract signers cannot pay transaction fees, the `ContractSigner` class does not provide a builder method for the _None_ witness scope. Furthermore, the `ContractSigner`'s builder methods can accept contract parameters if the contract's `verify(...)` method has extra parameters. -**Note:** A transaction requires at least one `AccountSigner` that will pay for the fees. +**Note:** A transaction requires at least one `AccountSigner` to pay for the fees. -> *A witness is a script pair that contains an invocation and a verification script. Both scripts are simply a -> sequence of NeoVM instructions. In the basic case of an account signer, the invocation script consists of the -> instruction to push the signature data on the NeoVM stack, whereas in the verification script, the corresponding -> public key data is pushed on the NeoVM stack followed by an instruction to check its signature provided in the -> invocation script. +> A witness is a script pair that consists of an invocation and a verification script. Both scripts are sequences of NeoVM instructions. In the case of an account signer, the invocation script includes instructions to push the signature data onto the NeoVM stack. In the verification script, the corresponding public key data is pushed onto the NeoVM stack, followed by an instruction to verify the signature provided in the invocation script. > -> Check out the [Medium article by NeoSPCC](https://neospcc.medium.com/thou-shalt-check-their-witnesses-485d2bf8375d) -> to learn more about witnesses and witness scopes. +> For more information on witnesses and witness scopes, refer to the [Medium article by NeoSPCC](https://neospcc.medium.com/thou-shalt-check-their-witnesses-485d2bf8375d). -Witnesses can only be added to the `Transaction` object and not to the builder because they usually depend on the -serialized transaction for producing a signature. In case you are using `single-sig` accounts in a transaction's -signers, the `sign()` method will produce the witnesses automatically for you. +Witnesses can only be added to the `Transaction` object, not to the builder, because they typically rely on the serialized transaction to produce a signature. If you are using `single-sig` accounts in a transaction's signers, the `sign()` method will automatically generate the witnesses for you. -The following is a simple example of how building, signing, and sending a transaction might look. +Here's a simple example of how to build, sign, and send a transaction: ```java Neow3j neow3j = Neow3j.build(new HttpService("http://127.0.0.1:40332")); @@ -90,30 +55,25 @@ Account account = Account.fromWIF("L24Qst64zASL2aLEKdJtRLnbnTbqpcRNWkWJ3yhDh2CLU byte[] script = new ScriptBuilder().contractCall(NeoToken.SCRIPT_HASH, "symbol", null) .toArray(); -Transaction tx = new TransactionBuilder(neow3j) +TransactionBuilder builder = new TransactionBuilder(neow3j) .script(script) - .signers(AccountSigner.calledByEntry(account)) - .sign(); + .signers(AccountSigner.calledByEntry(account)); -NeoSendRawTransaction response = tx.send(); +// Build the transaction +Transaction tx = builder.sign() + .send(); ``` -For manually adding witnesses to a transaction continue reading the next section. +To manually add witnesses to a transaction, continue reading the next section. ## Signing Transactions -As you have seen in the last section, the `TransactionBuilder` offers a `sign()` method. It attempts to add the correct -signatures according to what it finds in the list of signers. If you add an `AccountSigner` that holds a private key, -the `sign()` method can automatically create the signature/witness for that signer. If the account doesn't have a key, -e.g., because it is a multi-sig account, you will need to provide the witness manually. -Witnesses for `ContractSigners` are also added automatically with `sign()`. +As demonstrated in the section on [Building Transactions](#/neo-n3/dapp_development/transactions?id=building-transactions), the `TransactionBuilder` offers a `sign()` method to add the correct signatures based on the provided signers. If you use an `AccountSigner` with a private key, the `sign()` method will automatically generate the required signature/witness. However, if the account does not have a key (e.g., for a multi-sig account), you'll need to provide the witness manually. -To sign manually, use `getUnsignedTransaction()` on the builder and retrieve the transaction with an empty list of -witnesses. Now it is up to you to add the necessary witnesses. You can get the serialized transaction bytes and create -a witness from it as shown below. +`To sign manually, use `getUnsignedTransaction()` on the builder to retrieve the transaction without witnesses. Then, add the necessary witnesses by creating a witness from the serialized transaction bytes: ```java -Transaction tx = txBuilder.getUnsignedTransaction(); +Transaction tx = builder.getUnsignedTransaction(); Account account = Account.fromWIF("L24Qst64zASL2aLEKdJtRLnbnTbqpcRNWkWJ3yhDh2CLUtLdwYK2"); ECKeyPair keyPair = account.getECKeyPair(); byte[] txBytes = tx.getHashData(); @@ -122,11 +82,7 @@ tx.addWitness(witness); tx.send(); ``` -If your use case is more advanced and requires witnesses of `multi-sig` accounts, you can create an unsigned -`Transaction` with `getUnsignedTransaction()` and append the witnesses manually to the transaction with -one of the `addMultiSigWitness(...)` convenience methods. The following example shows how such an implementation could -look like with a multi-sig account of three participants that requires the signature of two of them. - +For more advanced use cases that require witnesses from multi-sig accounts, you can create an unsigned `Transaction` and manually append the witnesses using `addMultiSigWitness(...)` methods. Here's an example with a multi-sig account of three participants that requires the signature of two: ```java Neow3j neow3j = Neow3j.build(new HttpService("http://127.0.0.1:40332")); @@ -136,43 +92,41 @@ ECKeyPair.ECPublicKey pubKey2 = ...; ECKeyPair.ECPublicKey pubKey3 = ...; int threshold = 2; -// The multi-sig account holding its verification script. +// Create the multi-sig account with its verification script Account multiSigAccount = Account.createMultiSigAccount(Arrays.asList(pubKey1, pubKey2, pubKey3), threshold); -byte[] script = ...; +byte[] script = ...; // Define your script -// Create and get unsigned transaction. +// Create and get an unsigned transaction Transaction tx = new TransactionBuilder(neow3j) .script(script) .signers(AccountSigner.calledByEntry(multiSigAccount)) .getUnsignedTransaction(); -// Externally sign the transaction's hash data (tx.getHashData()) with e.g., Sign.signMessage(txHash, ecKeyPair); -// Then, parse the raw signature data into the Sign.SignatureData object. -byte[] rawSig1 = ...; +// Sign the transaction's hash data externally +byte[] rawSig1 = ...; // Signature from participant 1 +byte[] rawSig2 = ...; // Signature from participant 2 + Sign.SignatureData sigData1 = Sign.SignatureData.fromByteArray(rawSig1); -byte[] rawSig2 = ...; Sign.SignatureData sigData2 = Sign.SignatureData.fromByteArray(rawSig2); -// Create a map to specify what signature data belongs to which public key. +// Map signature data to public keys HashMap signatureMap = new HashMap<>(); signatureMap.put(pubKey1, sigData1); signatureMap.put(pubKey2, sigData2); -// Creates and adds a multi-sig witness to the transaction based on the verification script and the signatures. +// Add a multi-sig witness to the transaction based on the verification script and signatures tx.addMultiSigWitness(multiSigAccount.getVerificationScript(), signatureMap); +// Send the transaction NeoSendRawTransaction response = tx.send(); ``` -If you need to sign a transaction manually and also require a witness for a contract signer, you can use the method -`Witness.createContractWitness(List verifyParams)` to create a witness for the contract signer. Then, -add it with `addWitness(Witness witness)` to the transaction. +If you need to sign a transaction manually and require a witness for a contract signer, use `Witness.createContractWitness(List verifyParams)` to create a witness for the contract signer and add it to the transaction using `addWitness(Witness witness)`. ## Tracking Transactions -To track an issued transaction, you can use the method `track()` on the transaction instance. As soon as the -transaction is included in a block, you can retrieve its application log with the method `getApplicationLog()`. +To track an issued transaction, use the `track()` method on the transaction instance. You can then retrieve the application log as soon as the transaction is included in a block using `getApplicationLog()`: ```java tx.track().subscribe(blockIndex -> { @@ -182,24 +136,19 @@ tx.track().subscribe(blockIndex -> { }); ``` -If you call `getApplicationLog()` before the transaction is included in a block it throws an `RpcResponseErrorException` -with an error message, that the transaction is unknown or could not be found. +If you call `getApplicationLog()` before the transaction is included in a block, it will throw an `RpcResponseErrorException` indicating that the transaction is unknown or could not be found. + -## Adding additional Network Fees +## Adding Additional Network Fees -There are two kind of fees one has to pay for a transaction, the system fee and the network fee. The system fee is the -cost of resources consumed by the execution of a script on the NeoVM. It depends on the number and type of instructions -executed in the script. The network fee is paid for the size of the transaction and the effort needed for signature -verification. Adding a higher network fee than needed gives the transaction priority in the network. Neow3j -automatically fetches the necessary system and network fees for a transaction, but you can add an additional network fee -for priority. Use the method `additionalNetworkFee()` as in the example below. +Transactions involve two types of fees: system fee and network fee. The system fee covers the resources consumed by script execution on the NeoVM, while the network fee is based on the transaction size and effort required for signature verification. You can add an additional network fee for priority using `additionalNetworkFee()`: ```java Transaction tx = new TransactionBuilder(neow3j) .script(script) .signers(AccountSigner.calledByEntry(acc)) - .additionalNetworkFee(1_000_000L) + .additionalNetworkFee(1_000_000L) // Adds 1,000,000 GAS fractions (0.01 GAS) .sign(); ``` -This adds 1'000'000 GAS fractions to the network fee, which is 1'000'000 / 10^8 = 0.01 GAS. +This example adds 1,000,000 GAS fractions to the network fee for transaction priority. diff --git a/docs/neo-n3/dapp_development/wallets_and_accounts.md b/docs/neo-n3/dapp_development/wallets_and_accounts.md index 04f3d2e..d6694e5 100644 --- a/docs/neo-n3/dapp_development/wallets_and_accounts.md +++ b/docs/neo-n3/dapp_development/wallets_and_accounts.md @@ -1,10 +1,8 @@ # Wallets and Accounts -Accounts and wallets are important concepts in blockchain. A Neo account in its basic form is made up of an EC key pair. -From this EC key pair, a `script hash` and an `address` can be derived that are used to identify the account. +Accounts and wallets are important concepts in blockchain. A Neo account in its basic form consists of an EC key pair. From this EC key pair, a `script hash` and an `address` can be derived, which are used to identify the account. -Besides this simple form there are also multi-signature (multi-sig) accounts which are made up of multiple public keys that -participate in the account. Neow3j uses the same `Account` class to represent both single- and multi-sig accounts. +In addition to this simple form, there are also multi-signature (multi-sig) accounts that consist of multiple public keys participating in the account. Neow3j uses the same `Account` class to represent both single- and multi-sig accounts. A wallet is a collection of one or more accounts. @@ -16,12 +14,9 @@ The easiest way to create a new wallet is by using one of the static creation me Wallet w = Wallet.create(); ``` -This creates a wallet with a new account (with a new key pair). There are other versions of this method that allow us to -immediately encrypt the new private key or directly write the wallet to a file after creation. +This creates a wallet with a new account (with a new key pair). There are other versions of this method that allow you to immediately encrypt the new private key or directly write the wallet to a file after creation. -[NEP-6](https://github.com/neo-project/proposals/blob/master/nep-6.mediawiki) is the wallet standard for Neo. If you have a -NEP-6 wallet file exported from some other wallet software, you can use `fromNEP6Wallet(...)` which reads the wallet information -from the NEP-6 file. +[NEP-6](https://github.com/neo-project/proposals/blob/master/nep-6.mediawiki) is the wallet standard for Neo. If you have a NEP-6 wallet file exported from some other wallet software, you can use `fromNEP6Wallet(...)` to read the wallet information from the NEP-6 file. ```java String absoluteFileName = "/path/to/your/NEP6.wallet"; @@ -29,13 +24,9 @@ Wallet w = Wallet.fromNEP6Wallet(absoluteFileName) .name("NewName"); ``` -> **Note:** When reading the wallet from a NEP-6 wallet file, the private keys of the contained accounts will be -> encrypted until you call `decryptAllAccounts(String password)` on the wallet. An encrypted account cannot be used for -> signing transactions. +> **Note:** When reading the wallet from a NEP-6 wallet file, the private keys of the contained accounts will be encrypted until you call `decryptAllAccounts(String password)` on the wallet. An encrypted account cannot be used for signing transactions. -If you already have `Account` objects you can create a wallet with the static method `withAccounts(...)`. Furthermore, you can -manually set a name, version and [scrypt](https://en.wikipedia.org/wiki/Scrypt) parameters for the wallet. If nothing is -set, default values are used. +If you already have `Account` objects, you can create a wallet with the static method `withAccounts(...)`. Furthermore, you can manually set a name, version, and [scrypt](https://en.wikipedia.org/wiki/Scrypt) parameters for the wallet. If nothing is set, default values are used. ```java Wallet w = Wallet.withAccounts(Account.create()) @@ -43,65 +34,51 @@ Wallet w = Wallet.withAccounts(Account.create()) .version("1.0"); ``` -> **Note:** If you want to extract a wallet instance, e.g. as a data transfer object make sure to create a -> `NEP6Wallet` instance and use this instance. To do so, you will have to encrypt the wallet first and then call -> `toNEP6Wallet`. This automatically initiates `NEP6Account` instances for all accounts in the wallet. +> **Note:** If you want to extract a wallet instance, for example as a data transfer object (DTO), make sure to create a `NEP6Wallet` instance and use this instance. To do so, you will need to encrypt the wallet first and then call `toNEP6Wallet`. This automatically initializes `NEP6Account` instances for all accounts in the wallet. ## Accounts -Accounts in neow3j can be created with or without EC key material. If the private key of the account is available, the -account can be used for signing arbitrary data, which includes transactions or other raw data. +Accounts in neow3j can be created with or without EC key material. If the private key of the account is available, the account can be used for signing arbitrary data, which includes transactions or other raw data. -The following methods create an account with the private key available. +The following methods create an account with the private key available: - `create()` -- `new Account(ECkeyPair exKeyPair)` -- `fromNEP6Account(NEP6Account nep6Acct)` - Requires decryption of the private key with `decryptPrivateKey(...)`. +- `new Account(ECKeyPair ecKeyPair)` +- `fromNEP6Account(NEP6Account nep6Account)` - Requires decryption of the private key with `decryptPrivateKey(...)`. - `fromWIF(String wif)` -It is also possible to create an account without a private key. This applies for example for a multi-sig account where -only the public keys, or its derived verification script are known. You can create an account without a private key with -the following static methods: - +It is also possible to create an account without a private key. This applies, for example, to a multi-sig account where only the public keys or its derived verification script are known. You can create an account without a private key with the following static methods: + - `fromAddress(String address)` - `fromScriptHash(Hash160 scriptHash)` - `fromPublicKey(ECPublicKey publicKey)` - `fromVerificationScript(VerificationScript script)` -> **Note:** If you are working with Neo addresses or `watch-only` accounts (i.e., without a private key), you can use -> the `Hash160` class for that. However, if you are working with wallets, and you're using NEP-6 wallet files, you can -> use the `Account` class for that. +> **Note:** If you are working with Neo addresses or `watch-only` accounts (i.e., without a private key), you can use the `Hash160` class for that. However, if you are working with wallets and using NEP-6 wallet files, you can use the `Account` class for that. -An account can hold a label that is set to its address by default. If needed you can change it to a custom label with -the `label(String)` method. +An account can hold a label that is set to its address by default. If needed, you can change it to a custom label using the `label(String)` method. ```java Account a = Account.fromWIF("L3kCZj6QbFPwbsVhxnB8nUERDy4mhCSrWJew4u5Qh5QmGMfnCTda") .label("MyAccount"); ``` -> **Note:** When you want to extract a single account instance, e.g. as a data transfer object (dto) make sure to create a -> `NEP6Account` instance and use this instance. To do so, you will have to encrypt the account first and then call -> `toNEP6Account`. This conversion is automatically made for each account when creating a `NEP6Wallet` from a wallet instance. +> **Note:** When you want to extract a single account instance, for example as a data transfer object (DTO), make sure to create a `NEP6Account` instance and use this instance. To do so, you will need to encrypt the account first and then call `toNEP6Account`. This conversion is automatically performed for each account when creating a `NEP6Wallet` from a wallet instance. ## Multi-sig Accounts Multi-signature accounts can be created with the following methods: - `fromVerificationScript(VerificationScript script)` -- `fromNEP6Account(NEP6Account nep6Acct)` +- `fromNEP6Account(NEP6Account nep6Account)` - `createMultiSigAccount(List publicKeys, int signingThreshold)` -- `createMultiSigAccount(String address, int signingThreshold, int nrOfParticipants)` +- `createMultiSigAccount(String address, int signingThreshold, int numberOfParticipants)` + +The first two methods can be used for single- and multi-sig accounts. The verification script, available in the NEP6Account's script, contains all information needed about the multi-sig account. This includes the signing threshold, the number of participants, and the involved public keys. -The first two methods can be used for single- and multi-sig accounts. The verification script - which is available in -the NEP6Account's script - holds all information needed about the multi-sig account. This includes the signing -threshold, the number of participants, and the involved public keys. -In the latter two methods there is now verification script available. Therefore, one or both of signing threshold and -number of participants has to be specified explicitly in order such that the multi-sig account can be used as a signer in -transactions. The `TransactionBuilder` needs the signing threshold and number of participants to determine the network -fee that has to be paid for signing with the account. +In the latter two methods, no verification script is available. Therefore, one or both of the signing threshold and number of participants must be specified explicitly so that the multi-sig account can be used as a signer in transactions. The `TransactionBuilder` requires the signing threshold and number of participants to determine the network fee that must be paid for signing with the account. -Multi-sig accounts do not hold EC key pairs. That would defeat the purpose of multi-sig accounts, because +Multi-sig accounts do not hold EC key pairs. That would defeat the purpose of multi-sigaccounts, because their key material should be spread over multiple entities. In the following example a new mutli-sig account is created from three public keys. Its signing threshold is two, i.e., diff --git a/docs/neo-n3/faq.md b/docs/neo-n3/faq.md index e2ae7c4..861ae8e 100644 --- a/docs/neo-n3/faq.md +++ b/docs/neo-n3/faq.md @@ -6,50 +6,34 @@ This page contains questions that we've been asked in the past and might arise d ##### Why do I need docker installed for running the test framework? -The test framework runs a neo-node instance inside of a docker container. This allows you to test your smart contract -and invocations with a running Neo N3 blockchain. +The test framework runs a neo-node instance inside of a docker container. This allows you to test your smart contract and invocations with a running Neo N3 blockchain. ##### How can I make use of Neo's fine granularity for transaction signatures? -For this, we suggest you to read through -[this Medium article](https://neospcc.medium.com/thou-shalt-check-their-witnesses-485d2bf8375d) about the mechanisms -around signers, scopes and witnesses. +For this, we suggest you to read through [this Medium article](https://neospcc.medium.com/thou-shalt-check-their-witnesses-485d2bf8375d) about the mechanisms around signers, scopes and witnesses. ##### What is the difference between Witness Rules and the `@Permission` annotation on a smart contract? -> **TL;DR** Witness rules restrict/allow actions of a transaction, while @Permission defines which non-safe methods a -smart contract is allowed to invoke on other smart contracts. +> **TL;DR** Witness rules restrict/allow actions of a transaction, while @Permission defines which non-safe methods a smart contract is allowed to invoke on other smart contracts. -Witness rules (but also the `allowContracts` and `allowGroups` witness scopes) allow you to control the usage of your -signature on a per-transaction basis. It tells the NeoVM in which contracts it is allowed to use the provided -signature. If your invocation leads to a call to a contract not mentioned in your rules, then the called contract cannot -make changes on your behalf. +Witness rules (but also the `allowContracts` and `allowGroups` witness scopes) allow you to control the usage of your signature on a per-transaction basis. It tells the NeoVM in which contracts it is allowed to use the provided signature. If your invocation leads to a call to a contract not mentioned in your rules, then the called contract cannot make changes on your behalf. -On the other hand, the `@Permission` annotation on a smart contract restricts the calls that -the contract can make once deployed. I.e., it doesn't care about signatures but can be used to prohibit calling -arbitrary contracts from within a contract. These restrictions are applied to all invocations of that contract -(regardless of what is allowed in the transactions invoking it). +On the other hand, the `@Permission` annotation on a smart contract restricts the calls that the contract can make once deployed. I.e., it doesn't care about signatures but can be used to prohibit calling arbitrary contracts from within a contract. These restrictions are applied to all invocations of that contract (regardless of what is allowed in the transactions invoking it). -Both concepts are used to reduce the attack surface on a transaction. Note, that permissions only apply when it's a -contract call that changes state or emits notifications. Reading from one contract to another won't be restricted with -the `@Permission` annotation. +Both concepts are used to reduce the attack surface on a transaction. Note, that permissions only apply when it's a contract call that changes state or emits notifications. Reading from one contract to another won't be restricted with the `@Permission` annotation. ### SDK - dApp Development ##### What RPC is used to relay a transaction that I will pay for, and which ones are just for reading? -The RPC `sendrawtransaction` is used to relay transactions that have been signed and will persist on-chain (i.e., it -costs GAS). The RPCs `invokefunction` and `invokescript` are read-only and can be used to "mock" invocations to figure -out what would happen if this function or script was invoked/executed in a signed transaction. +The RPC `sendrawtransaction` is used to relay transactions that have been signed and will persist on-chain (i.e., it costs GAS). The RPCs `invokefunction` and `invokescript` are read-only and can be used to "mock" invocations to figure out what would happen if this function or script was invoked/executed in a signed transaction. ##### How does the node validate a witness check when I only use read invocations? -When invoking methods with `invokefunction` or `invokescript` RPCs, calls to `checkWitness` return true as long as the -correct signers (with the correct scope) are attached in the request. +When invoking methods with `invokefunction` or `invokescript` RPCs, calls to `checkWitness` return true as long as the correct signers (with the correct scope) are attached in the request. ### Devpack - Smart Contract Development No FAQs yet for the devpack. -**Please reach out to us in our [Discord Server](https://discord.gg/RBukhnEeke) if you think there are questions and -answers that we should add on this page.** +**Please reach out to us in our [Discord Server](https://discord.gg/RBukhnEeke) if you think there are questions and answers that we should add on this page.** diff --git a/docs/neo-n3/smart_contract_development/debugging.md b/docs/neo-n3/smart_contract_development/debugging.md index 349d56d..9b9e609 100644 --- a/docs/neo-n3/smart_contract_development/debugging.md +++ b/docs/neo-n3/smart_contract_development/debugging.md @@ -1,23 +1,11 @@ # Debugging -By default, the `neow3jCompile` Gradle task will output a `.nefdbgnfo` file that contains debugging information for the -compiled smart contract. The file is placed in the same folder as the NEF and contract manifest, i.e., usually at -`./build/neow3j`. The file is actually a zip archive containing a JSON file, if you want to take a look inside. +By default, the `neow3jCompile` Gradle task will output a `.nefdbgnfo` file that contains debugging information for the compiled smart contract. The file is placed in the same folder as the NEF and contract manifest, i.e., usually at `./build/neow3j`. The file is actually a zip archive containing a JSON file, if you want to take a look inside. -The debugging information is meant to be used with the [Neo -Debugger](https://github.com/neo-project/neo-debugger), which is part of the VS Code extension pack called -[Neo Blockchain Toolkit](https://marketplace.visualstudio.com/items?itemName=ngd-seattle.neo-blockchain-toolkit). -Smart Contract debugging is not possible in IntelliJ. From here on we assume you are working in VS Code and have the Neo -Blockchain Toolkit extension installed. +The debugging information is meant to be used with the [Neo Debugger](https://github.com/neo-project/neo-debugger), which is part of the VS Code extension pack called [Neo Blockchain Toolkit](https://marketplace.visualstudio.com/items?itemName=ngd-seattle.neo-blockchain-toolkit). Smart Contract debugging is not possible in IntelliJ. From here on we assume you are working in VS Code and have the Neo Blockchain Toolkit extension installed. + +For VS Code to know what contract to debug, you need to add a launch configuration. Launch configuration are in the file `.vscode/launch.json` in your projecet directory. If there is no such file yet, you can generate it by selecting "Add Configuration" from the "Run" menu. In `launch.json` move your cursor inside the "configurations" section and use autocompletion, such that an input box will appear containing an entry "*Neo Contract: Launch*". Select it, and a new configuration will be added. Adapt the configuration similarly to the following example. The `program` property has to point to the NEF file that was output by the neow3j Gradle plugin. For more information on how to configure a launch configuration for the Neo Debugger head over to one of the creator's [examples](https://github.com/devhawk/safe-purchase-sample/blob/master/.vscode/launch.json). -For VS Code to know what contract to debug, you need to add a launch configuration. Launch configuration are in the file -`.vscode/launch.json` in your projecet directory. If there is no such file yet, you can generate it by selecting "Add -Configuration" from the "Run" menu. -In `launch.json` move your cursor inside the "configurations" section and use autocompletion, such that an input box -will appear containing an entry "*Neo Contract: Launch*". Select it, and a new configuration will be added. Adapt the -configuration similarly to the following example. The `program` property has to point to the NEF file that was output by -the neow3j Gradle plugin. For more information on how to configure a launch configuration for the Neo Debugger head over -to one of the creator's [examples](https://github.com/devhawk/safe-purchase-sample/blob/master/.vscode/launch.json). Here's the excerpt from neow3j's boilerplate project. ```json @@ -40,9 +28,7 @@ Here's the excerpt from neow3j's boilerplate project. } ``` -With the configuration in place you can start debugging by pressing F5 or use "Debug: Start Debugging" from the Command -Palette. +With the configuration in place you can start debugging by pressing F5 or use "Debug: Start Debugging" from the Command Palette. > **Note** -Currently, debugging is only supported inside of the contract class. If the class makes calls to methods in the devpack -or in other custom classes in your workspace, the debugger will not step into those methods. +Currently, debugging is only supported inside of the contract class. If the class makes calls to methods in the devpack or in other custom classes in your workspace, the debugger will not step into those methods. diff --git a/docs/neo-n3/smart_contract_development/deployment.md b/docs/neo-n3/smart_contract_development/deployment.md index 66a53c2..7747db1 100644 --- a/docs/neo-n3/smart_contract_development/deployment.md +++ b/docs/neo-n3/smart_contract_development/deployment.md @@ -1,16 +1,10 @@ # Deployment -You can deploy smart contracts with different tools from the Neo ecosystem, for example, with the Neo Blockchain -Toolkit. Here, we show how to deploy with neow3j. In our smart contract projects, we like to use a separate source set -to hold deployment related code. Adding such a source set is described in the -[Setup](neo-n3/smart_contract_development/setup_and_compilation.md) guide. +You can deploy smart contracts with different tools from the Neo ecosystem, for example, with the Neo Blockchain Toolkit. Here, we show how to deploy with neow3j. In our smart contract projects, we like to use a separate source set to hold deployment related code. Adding such a source set is described in the [Setup](neo-n3/smart_contract_development/setup_and_compilation.md) guide. The [boilerplate](https://github.com/neow3j/neow3j-boilerplate) repository shows how this could look like. -The central class for deployment is `ContractManagement` that was introduced -[here](neo-n3/dapp_development/smart_contracts.md#ContractManagement) and is part of neow3j SDK. Thus, you need the -module `io.neow3j:contract`. See the [Quickstart](README.md#quickstart) section on how to import it. -Before you calling the `ContractManagement` contract, we need to compile our contract code. +The central class for deployment is `ContractManagement` that was introduced [here](neo-n3/dapp_development/smart_contracts.md#ContractManagement) and is part of neow3j SDK. Thus, you need the module `io.neow3j:contract`. See the [Quickstart](README.md#quickstart) section on how to import it. Before you calling the `ContractManagement` contract, we need to compile our contract code. ```java CompilationUnit res = new Compiler().compile(HelloWorldSmartContract.class.getCanonicalName(), substitutions); @@ -28,11 +22,7 @@ Hash256 txHash = builder.sign().send().getSendRawTransaction().getHash(); Await.waitUntilTransactionIsExecuted(txHash, neow3j); ``` -Note that we're also passing `hash160(owner)` to the `ContractManagement`'s `deploy` method as a parameter. That -parameter will be passed to the `_deploy` method of your contract, so you can use it to configure your contract at time -of deployment. The `ContractManagement` contract will deploy your contract and then call the `_deploy` method on it. -You can add this method to your contract by annotating a method with `@OnDeployment` (see -[here](neo-n3/smart_contract_development/devpack.md#_deploy)). Here's an example for such a method. +Note that we're also passing `hash160(owner)` to the `ContractManagement`'s `deploy` method as a parameter. That parameter will be passed to the `_deploy` method of your contract, so you can use it to configure your contract at time of deployment. The `ContractManagement` contract will deploy your contract and then call the `_deploy` method on it. You can add this method to your contract by annotating a method with `@OnDeployment` (see [here](neo-n3/smart_contract_development/devpack.md#_deploy)). Here's an example for such a method. ```java @OnDeployment @@ -43,12 +33,9 @@ public static void deploy(Object data, boolean update) { } ``` -Above we passed `hash160(owner)` as a deploy parameter, but, if you want to pass multiple parameters use -`ContractParameter.array(...)` and add all parameters to it. +Above we passed `hash160(owner)` as a deploy parameter, but, if you want to pass multiple parameters use `ContractParameter.array(...)` and add all parameters to it. -Finally, To get the newly deployed contract's hash you can execute the code below. The hash depends on the sender of the -deploy transaction, the NEF checksum and the contract's name. The hash does not change even if you update the contract -in the future. +Finally, To get the newly deployed contract's hash you can execute the code below. The hash depends on the sender of the deploy transaction, the NEF checksum and the contract's name. The hash does not change even if you update the contract in the future. ```java Hash160 contractHash = SmartContract.getContractHash( diff --git a/docs/neo-n3/smart_contract_development/devpack.md b/docs/neo-n3/smart_contract_development/devpack.md index 47b4139..2987d6c 100644 --- a/docs/neo-n3/smart_contract_development/devpack.md +++ b/docs/neo-n3/smart_contract_development/devpack.md @@ -77,18 +77,13 @@ class MyContract extends ContractInterface { } ``` -In this minimal form the class only provides access to the contract's hash via the `getHash()` method inherited from -`ContractInterface`. Any other contract methods have to be added according to their signature in the contract's -manifest. Assuming the contract has a method `findElement` with a `ByteString` parameter and a `ByteString` return type, -you would need to add the following method. Note that the method needs to be native. A method body implementation is not necessary, since this is only an interface to an actual contract instance on the blockchain. +In this minimal form the class only provides access to the contract's hash via the `getHash()` method inherited from `ContractInterface`. Any other contract methods have to be added according to their signature in the contract's manifest. Assuming the contract has a method `findElement` with a `ByteString` parameter and a `ByteString` return type, you would need to add the following method. Note that the method needs to be native. A method body implementation is not necessary, since this is only an interface to an actual contract instance on the blockchain. ```java public native ByteString findElement(ByteString key); ``` -The devpack provides abstract contract interfaces that already contain the API of contracts following a standard. For example, -if you want to establish a contract interface to a fungible token contract, you can extend the `FungibleToken` class. All methods -of a NEP-17 token contract are already available and you can just add extra methods that your contract might hold (simply add them as shown before). +The devpack provides abstract contract interfaces that already contain the API of contracts following a standard. For example, if you want to establish a contract interface to a fungible token contract, you can extend the `FungibleToken` class. All methods of a NEP-17 token contract are already available and you can just add extra methods that your contract might hold (simply add them as shown before). ```java class MyTokenContract extends FungibleToken { @@ -113,17 +108,11 @@ Checkout the `io.neow3j.devpack.contracts` package for more such contract interf ### StdLib -When using the `StdLib.jsonSerialize(Object o)` method for a value or object that contains a byte string or byte array -(e.g., `ByteString`, `byte[]`, or `Hash160`) make sure to first Base64-encoded that value. Otherwise, it will be -interpreted as a UTF-8 encoded string, which might lead to errors. It will not be presented in the JSON as a hexadecimal -string. +When using the `StdLib.jsonSerialize(Object o)` method for a value or object that contains a byte string or byte array (e.g., `ByteString`, `byte[]`, or `Hash160`) make sure to first Base64-encoded that value. Otherwise, it will be interpreted as a UTF-8 encoded string, which might lead to errors. It will not be presented in the JSON as a hexadecimal string. ### Neo Name Service -The Neo Name Service contract (NNS) is technically not a native contract but is maintained and issued by the Neo -Foundation. The devpack provides a contract interface to the NNS with the class -`io.neow3j.devpack.contracts.NeoNameService`. Note, that this class does not have a fixed script hash, since it is not a -native contract. If you want to use the class in your contract you can simply initialize an instance of it. +The Neo Name Service contract (NNS) is technically not a native contract but is maintained and issued by the Neo Foundation. The devpack provides a contract interface to the NNS with the class `io.neow3j.devpack.contracts.NeoNameService`. Note, that this class does not have a fixed script hash, since it is not a native contract. If you want to use the class in your contract you can simply initialize an instance of it. ```java new NeoNameService("a92fbe5bf164170a624474841485b20b45a26047"); @@ -133,9 +122,7 @@ Make sure that the script hash is equal to the current script hash of the NNS co ## Events -Neo smart contracts can fire events. They appear, for example, in the [application -logs](https://docs.neo.org/v3/docs/en-us/reference/rpc/latest-version/api/getapplicationlog.html) of a contract -invocation. The events that a contract can fire are listed in its manifest. The JSON below shows how this could look. +Neo smart contracts can fire events. They appear, for example, in the [application logs](https://docs.neo.org/docs/n3/reference/rpc/getapplicationlog.html) of a contract invocation. The events that a contract can fire are listed in its manifest. The JSON below shows how this could look. ```json "events": [ @@ -155,13 +142,9 @@ invocation. The events that a contract can fire are listed in its manifest. The ] ``` -An event is defined by its name and the state parameters that are passed with it. The devpack allows you to define and -use events with up to 16 state parameters. The classes representing these events are located in the -[`io.neow3j.devpack.events`](https://javadoc.io/doc/io.neow3j/devpack/latest/io/neow3j/devpack/events/package-summary.html) -package. +An event is defined by its name and the state parameters that are passed with it. The devpack allows you to define and use events with up to 16 state parameters. The classes representing these events are located in the [`io.neow3j.devpack.events`](https://javadoc.io/doc/io.neow3j/devpack/latest/io/neow3j/devpack/events/package-summary.html) package. -Events are declared in static contract variables as shown in the following code snippet. They cannot -be declared inside of a method body or in classes that are not the main contract class. +Events are declared in static contract variables as shown in the following code snippet. They cannot be declared inside of a method body or in classes that are not the main contract class. ```java @DisplayName("mint") @@ -171,11 +154,7 @@ be declared inside of a method body or in classes that are not the main contract private static Event2Args onTransfer; ``` -It is not necessary to initialize the variables with an actual instance. This is counter-intuitive for a Java developer, -but, the variables are not meant to have an actual value. They are only definitions, with a name and the number and -types of state parameters. All event classes follow the naming schema `Event[n]Args`, where `n` is the number of state -parameters the event takes. The `@DisplayName` annotation is optional and can be used to define a different name for the -event than the variable name. If it is not used, the variable name is the event name. +It is not necessary to initialize the variables with an actual instance. This is counter-intuitive for a Java developer, but, the variables are not meant to have an actual value. They are only definitions, with a name and the number and types of state parameters. All event classes follow the naming schema `Event[n]Args`, where `n` is the number of state parameters the event takes. The `@DisplayName` annotation is optional and can be used to define a different name for the event than the variable name. If it is not used, the variable name is the event name. Once an event is declared, it can then be used in contract methods by calling its `fire(...)` method. @@ -192,64 +171,39 @@ Once an event is declared, it can then be used in contract methods by calling it ## Special Contract Methods -There are a couple of contract methods that have a special purpose. The neow3j devpack provides annotations to mark them -in your contract code. Using the annotations will make it easier to spot the methods in your code and allows the -compiler to make checks that help finding errors in these methods faster. +There are a couple of contract methods that have a special purpose. The neow3j devpack provides annotations to mark them in your contract code. Using the annotations will make it easier to spot the methods in your code and allows the compiler to make checks that help finding errors in these methods faster. ### _deploy -This method is called right after a contract is deployed or updated. More precisely, the *ContractManamgement* contract -will call this method on your contract when you invoke `deploy` or `update` on the *ContractManagement*. You can use it -to setup and configure your contract at deploy-time. -Use the devpack's `io.neow3j.devpack.annotations.OnDeployment` annotation on the designated method. Your method's name -does not have to be `_deploy`, but can be anything. Although, in the contract manifest it will show up under the name -`_deploy`. The method's signature must be `void methodName(Object data, boolean isUpdate)`. +This method is called right after a contract is deployed or updated. More precisely, the *ContractManamgement* contract will call this method on your contract when you invoke `deploy` or `update` on the *ContractManagement*. You can use it to setup and configure your contract at deploy-time. Use the devpack's `io.neow3j.devpack.annotations.OnDeployment` annotation on the designated method. Your method's name does not have to be `_deploy`, but can be anything. Although, in the contract manifest it will show up under the name `_deploy`. The method's signature must be `void methodName(Object data, boolean isUpdate)`. ### verify -This method is called if your contract is invoked with the verification trigger. For example, when a contract owns -tokens and you issue a withdraw transaction that transfers those tokens to another account/contract, the contract -is called with the verification trigger. In other words the contract's `verify` method is called. Most often the -`verify` method contains a simple witness check on the owner of the contract. -Use the devpack's `io.neow3j.devpack.annotations.OnVerification` annotation on the designated method. Your method's name -does not have to be `verify`, but can be anything. Although, in the contract manifest it will show up under the name -`verify`. The method must return a boolean and can have any number of parameters. +This method is called if your contract is invoked with the verification trigger. For example, when a contract owns tokens and you issue a withdraw transaction that transfers those tokens to another account/contract, the contract is called with the verification trigger. In other words the contract's `verify` method is called. Most often the `verify` method contains a simple witness check on the owner of the contract. + +Use the devpack's `io.neow3j.devpack.annotations.OnVerification` annotation on the designated method. Your method's name does not have to be `verify`, but can be anything. Although, in the contract manifest it will show up under the name `verify`. The method must return a boolean and can have any number of parameters. >**Note:** The Neo node does not allow the verify method to fire any event. The compiler will throw an exception >if an event is fired within this method. ### onNEP17Payment -Your contract requires this method to be able to receive tokens from NEP-17 contracts, i.e., fungible tokens like NEO or -GAS. Any contract that follows the NEP-17 standard will call this method on your contract if some of its tokens are -transferred to your contract. -Use the devpack's `io.neow3j.devpack.annotations.OnNEP17Payment` annotation on the designated method. Your method's name -does not have to be `onNEP17Payment`, but can be anything. Although, in the contract manifest it will show up under the -name `onNEP17Payment`. The method's signature must be `void methodName(Hash160 sender, int amount, Object data)`. +Your contract requires this method to be able to receive tokens from NEP-17 contracts, i.e., fungible tokens like NEO or GAS. Any contract that follows the NEP-17 standard will call this method on your contract if some of its tokens are transferred to your contract. + +Use the devpack's `io.neow3j.devpack.annotations.OnNEP17Payment` annotation on the designated method. Your method's name does not have to be `onNEP17Payment`, but can be anything. Although, in the contract manifest it will show up under the name `onNEP17Payment`. The method's signature must be `void methodName(Hash160 sender, int amount, Object data)`. ### onNEP11Payment -Your contract requires this method to be able to receive tokens from NEP-17 contracts, i.e., non-fungible tokens. Any -contract that follows the NEP-11 standard will call this method on your contract if some of its tokens are transferred -to your contract. Use the devpack's `io.neow3j.devpack.annotations.OnNEP11Payment` annotation on the designated method. -Your method's name does not have to be `onNEP11Payment`, but can be anything. Although, in the contract manifest it will -show up under the name `onNEP11Payment`. The method's signature must be `void methodName(Hash160 sender, int amount, -ByteString tokenId, Object data)`. +Your contract requires this method to be able to receive tokens from NEP-17 contracts, i.e., non-fungible tokens. Any contract that follows the NEP-11 standard will call this method on your contract if some of its tokens are transferred to your contract. Use the devpack's `io.neow3j.devpack.annotations.OnNEP11Payment` annotation on the designated method. Your method's name does not have to be `onNEP11Payment`, but can be anything. Although, in the contract manifest it will show up under the name `onNEP11Payment`. The method's signature must be `void methodName(Hash160 sender, int amount, ByteString tokenId, Object data)`. ## Permissions, Trusts, Groups, Safe Methods, and Call Flags -The basis of authorization on the Neo blockchain are cryptographic signatures. Users attach signatures to contract -invocations to proove that they are authorized to perform certain actions in a smart contract. This authorization can be -misused by smart contracts. A malicious contract can use the signature to perform a token transfer unintended by the -user. To prevent that, Neo applies witness scopes that allow the user to restrict the use of their witness/signature. By -default a witness is only valid in the contract that is the entry point of an invocation. The scope can be extended to -specific contracts, groups of contracts or to a global scope. +The basis of authorization on the Neo blockchain are cryptographic signatures. Users attach signatures to contract invocations to proove that they are authorized to perform certain actions in a smart contract. This authorization can be misused by smart contracts. A malicious contract can use the signature to perform a token transfer unintended by the user. To prevent that, Neo applies witness scopes that allow the user to restrict the use of their witness/signature. By default a witness is only valid in the contract that is the entry point of an invocation. The scope can be extended to specific contracts, groups of contracts or to a global scope. ### Groups -Smart contract groups are designated by an EC public key. The contract manifest contains the affiliation of a contract -with a group as shown below. +Smart contract groups are designated by an EC public key. The contract manifest contains the affiliation of a contract with a group as shown below. ```json "groups": [ @@ -260,13 +214,7 @@ with a group as shown below. ], ``` -The public key identifies the group and the signature is proof that the originator of the contract was in possession of -the corresponding private key material. The signature is created from the contract's hash and needs to be -Base64-encoded. Thus, if you want to add your contract to a group you first need to compile it, calculate the contract -hash, create the signature over that hash and extend the contract manifest with the group's public key and the produced -signature. Note, that the contract hash depends on the account used to deploy the contract. I.e., you need to know in -advance which account you will use to deploy the contract. To retrieve the contract hash and produce the signature you -can use the neow3j SDK as in the following example code. +The public key identifies the group and the signature is proof that the originator of the contract was in possession of the corresponding private key material. The signature is created from the contract's hash and needs to be Base64-encoded. Thus, if you want to add your contract to a group you first need to compile it, calculate the contract hash, create the signature over that hash and extend the contract manifest with the group's public key and the produced signature. Note, that the contract hash depends on the account used to deploy the contract. I.e., you need to know in advance which account you will use to deploy the contract. To retrieve the contract hash and produce the signature you can use the neow3j SDK as in the following example code. ```java Hash160 sender = ...; @@ -279,22 +227,13 @@ Sign.SignatureData sig = Sign.signMessage(contractHash.toArray(), keyPair); String encSig = Base64.encode(sig.getConcatenated()); ``` -You will have to modify the contract manifest JSON file and add the produced encoded signature and the public -key to the `groups` section manually. +You will have to modify the contract manifest JSON file and add the produced encoded signature and the public key to the `groups` section manually. ### Permissions -Besides witness scopes, smart contract security is improved by a system of permissions and trusts that a contract -developer can define for her contract. Permissions define which contracts your contract is permitted to call. They are -actively enforced, meaning that once defined in the contract's manifest, any calls from within your contract to -contracts and methods not contained in the permissions will fail. To define permissions use the -`io.neow3j.devpack.annotations.Permission` annotation on class level of your contract class. By default your contract -will have no permissions. +Besides witness scopes, smart contract security is improved by a system of permissions and trusts that a contract developer can define for her contract. Permissions define which contracts your contract is permitted to call. They are actively enforced, meaning that once defined in the contract's manifest, any calls from within your contract to contracts and methods not contained in the permissions will fail. To define permissions use the `io.neow3j.devpack.annotations.Permission` annotation on class level of your contract class. By default your contract will have no permissions. -The following is an example configuration. It allows your contract to call any method of the contract -with hash `726cb6e0cd8628a1350a611384688911ab75f51b`, the methods `getBalance` and `transfer` of the contract with hash -`d2a4cff31913016155e38e474a2c06d08be276cf`, and the method `commonMethodName` of any contract in the group with public key -`033a4d051b04b7fc0230d2b1aaedfd5a8 4be279a5361a7358db665ad7857787f1b`. +The following is an example configuration. It allows your contract to call any method of the contract with hash `726cb6e0cd8628a1350a611384688911ab75f51b`, the methods `getBalance` and `transfer` of the contract with hash `d2a4cff31913016155e38e474a2c06d08be276cf`, and the method `commonMethodName` of any contract in the group with public key `033a4d051b04b7fc0230d2b1aaedfd5a8 4be279a5361a7358db665ad7857787f1b`. ```java @Permission(contract = "726cb6e0cd8628a1350a611384688911ab75f51b", methods = "*") @@ -303,10 +242,7 @@ with hash `726cb6e0cd8628a1350a611384688911ab75f51b`, the methods `getBalance` a public class MyContract { ``` -To set a permission for a native contract, you can instead use the `nativeContract` field in the annotation together with -the enum `NativeContract`. As you may have noticed, the second permission in the example code above refers to the native -GasToken contract. As it is a native contract, you can instead also use the following annotation, which results in the -exact same outcome. +To set a permission for a native contract, you can instead use the `nativeContract` field in the annotation together with the enum `NativeContract`. As you may have noticed, the second permission in the example code above refers to the native GasToken contract. As it is a native contract, you can instead also use the following annotation, which results in the exact same outcome. ```java @Permission(nativeContract = NativeContract.GasToken, methods = {"getBalance", "transfer"}) @@ -317,13 +253,9 @@ If you want to allow your contract to call any other contract, use the wildcard ### Trusts -Trusts define what contracts can call your contract, but, in contrast to permissions they are not enforeced. I.e., you -cannot deter other contracts from calling yours. Trusts are only a definition that wallets and other dApps can use to -tell the user when a contract is invoked that doesn't trust the calling contract. +Trusts define what contracts can call your contract, but, in contrast to permissions they are not enforeced. I.e., you cannot deter other contracts from calling yours. Trusts are only a definition that wallets and other dApps can use to tell the user when a contract is invoked that doesn't trust the calling contract. -By default the trust property is empty, i.e., no contracts are trusted. Use the `io.neow3j.devpack.annotations.Trust` -annotation to define trusts like in the following example. The first entry is based on a single smart contract hash and -the second one on a public key of a contract group. +By default the trust property is empty, i.e., no contracts are trusted. Use the `io.neow3j.devpack.annotations.Trust` annotation to define trusts like in the following example. The first entry is based on a single smart contract hash and the second one on a public key of a contract group. ```java @Trust(contract = "acce6fd80d44e1796aa0c2c625e9e4e0ce39efc0") @@ -331,9 +263,7 @@ the second one on a public key of a contract group. public class MyContract { ``` -To trust a native contract, instead of adding its hash to the `contract` attribute, you can use the `nativeContract` -attribute the same way as it is used in the `@Permission` annotation as specified -[above](neo-n3/smart_contract_development/devpack.md#Permissions). In the following example, the native StdLib is trusted: +To trust a native contract, instead of adding its hash to the `contract` attribute, you can use the `nativeContract` attribute the same way as it is used in the `@Permission` annotation as specified [above](neo-n3/smart_contract_development/devpack.md#Permissions). In the following example, the native StdLib is trusted: ```java @Trust(nativeContract = NativeContract.StdLib) @@ -344,34 +274,24 @@ If you want to trust any contract use the wildcard option `@Trust("*")`. ### Safe Methods -Methods that don't change state of a contract and don't fire events can be safely invoked in a read-only mode. To signal -that to the Neo network, you can use the `io.neow3j.devpack.annotations.Safe` annotation on method-level. The method -will be tagged as safe in the contract's manifest. +Methods that don't change state of a contract and don't fire events can be safely invoked in a read-only mode. To signal that to the Neo network, you can use the `io.neow3j.devpack.annotations.Safe` annotation on method-level. The method will be tagged as safe in the contract's manifest. If your `@Safe`-annotate a method does change state or fire an event, invocations of that method will fail. ### Call Flags -Call flags allow you to restrict the actions of a contract you call within your contract. For example, you can deny -further calls to other contracts, changing blockchain state, or firing events. +Call flags allow you to restrict the actions of a contract you call within your contract. For example, you can deny further calls to other contracts, changing blockchain state, or firing events. -The possible flags are defined and docuemented in `io.neow3j.devpack.constants.CallFlags` and are ment to be used in the -`call` method of the `io.neow3j.devpack.Contract` class. +The possible flags are defined and docuemented in `io.neow3j.devpack.constants.CallFlags` and are ment to be used in the `call` method of the `io.neow3j.devpack.Contract` class. ## Placeholder Substitution -The devpack offers the possibility to substitute strings used in a contract before compiling it. Any string literal in -the main contract class can be substituted, even annotation values. Currently, this feature is not supported in -auxiliary classes used in the contract class. +The devpack offers the possibility to substitute strings used in a contract before compiling it. Any string literal in the main contract class can be substituted, even annotation values. Currently, this feature is not supported in auxiliary classes used in the contract class. You have to compile the contract programmatically to be able to use this feature. Checkout -[this](neo-n3/smart_contract_development/setup_and_compilation.md#programmatic-compilation) section for information on -how to compile programmatically. The `Compiler` provides a `compile` method that takes a `Map` -parameter. This is the substitution map that tells the compiler which strings are placeholder strings (the map's keys) -and which values they should be replaced with (the map's values). The placeholders in the contract must follow the -syntax `"${*}"` where `*` will be used as key in the substitution map. +[this](neo-n3/smart_contract_development/setup_and_compilation.md#programmatic-compilation) section for information on how to compile programmatically. The `Compiler` provides a `compile` method that takes a `Map` parameter. This is the substitution map that tells the compiler which strings are placeholder strings (the map's keys) and which values they should be replaced with (the map's values). The placeholders in the contract must follow the syntax `"${*}"` where `*` will be used as key in the substitution map. ```java Map substitutionMap = new HashMap<>(); @@ -404,15 +324,9 @@ Here's an example of how a smart contract using placeholders might look. } ``` -> **Note:** If the placeholder is not specified in the substitution map when compiling, the string present -in the contract will be used (given that this value is not restricted to any format). For example, `"${account_address}"` -must be replaced with a valid address for the compilation not to fail, while `event` will be called `"${event_name}"` if -`"event_name"` is not a key in the substitution map and thus no substitution is provided. - -The placeholder substitution feature works in contract tests too. See -[this](neo-n3/smart_contract_development/testing.md#deployment-configuration) section for more information. - +> **Note:** If the placeholder is not specified in the substitution map when compiling, the string present in the contract will be used (given that this value is not restricted to any format). For example, `"${account_address}"` must be replaced with a valid address for the compilation not to fail, while `event` will be called `"${event_name}"` if `"event_name"` is not a key in the substitution map and thus no substitution is provided. +The placeholder substitution feature works in contract tests too. See [this](neo-n3/smart_contract_development/testing.md#deployment-configuration) section for more information.