Merge pull request #115 from chenzhitong/update-contract

Updated documentation for contract development
neo-project · Jun 11, 2024 · 313c3e8 · 313c3e8
2 parents 6e66cc5 + 3ad8f27
commit 313c3e8
Show file tree

Hide file tree

Showing 6 changed files with 63 additions and 62 deletions.
diff --git a/docs/n3/develop/deploy/invoke.md b/docs/n3/develop/deploy/invoke.md
@@ -113,8 +113,8 @@ Three fields related to the contract invocation permission are defined in the co
 | Fields        | Type                          | Description                                                  |
 | ------------- | ----------------------------- | ------------------------------------------------------------ |
 | `Groups`      | `ContractGroup[]`             | Defines a group of trusted contracts, consisting of a public key and a signature of contract hash. |
-| `Permissions` | `ContractPermission[]`        | This field is an array containing a permission object, which defines other contracts and methods that the contract wants to call. The contract can be ScriptHash, Group, or wildcard \*. The method is the method name or wildcard \*. Contracts or methods not declared in the manifest cannot be called by the contract. |
-| `Trusts`      | `WildcardContainer<UInt160>` | Defines other contracts trusted by the contract. The contract can be ScriptHash, Group, or wildcard *. If a contract is trusted, the user will not receive any warning message when the contract is called. |
+| `Permissions` | `ContractPermission[]`        | This field is an array containing a permission object, which defines other contracts and methods that the contract wants to call. The contract can be ScriptHash, Group, or `Permission.Any`. The method is the method name or `Method.Any`. Contracts or methods not declared in the manifest cannot be called by the contract. |
+| `Trusts`      | `WildcardContainer<ContractPermissionDescriptor>` | Defines other contracts trusted by the contract. The contract can be ScriptHash, Group, or `Permission.Any`. If a contract is trusted, the user will not receive any warning message when the contract is called. |
 
 Assuming that the contract A calls the contract B, the following table details the invoking behavior and wallet behavior of the contract in various setting scenarios.
 
@@ -125,8 +125,8 @@ Assuming that the contract A calls the contract B, the following table details t
 | Permissions of contract A  include contract B<br/>Trusts of contract B include contract A | None                                                         | Default and adds CustomContract                              | Yes                         |
 | Permissions of contract A  include contract B<br/>Trusts of contract B do not include contract A | Prompts that contract A will call contract B, and asks whether to authorize the signature to contract B. | Default and adds CustomContract        according to the user's decision | Determined by the user      |
 | Permissions of contract A include a Groups B                 | Prompts that contract A will call any contract in group B and asks whether to authorize the signature to group B. | Default and adds CustomGroups according to the user's decision | Determined by the user      |
-| The contract defined in the Permissions of contract A is wildcard * and the method is m<br/>{"contract":"\*", "method": "m"} | Prompts that contract A will call the method m of any contract and asks whether to authorize the signature to contract B. | Default or Global according to the user's decision           | Determined by the user      |
-| The contract defined in the Permissions of contract A is wildcard * and the method is wildcard \*<br/>{"contract":"\*", "method": "\*"} | Prompts that contract A will call any method of any contract and asks whether to set the signature to Global. | Default or Global according to the user's decision           | Determined by the user      |
+| The contract defined in the Permissions of contract A is Permission.Any * and the method is m<br/>{"contract":"\*", "method": "m"} | Prompts that contract A will call the method m of any contract and asks whether to authorize the signature to contract B. | Default or Global according to the user's decision           | Determined by the user      |
+| The contract defined in the Permissions of contract A is Permission.Any * and the method is Method.Any \*<br/>{"contract":"\*", "method": "\*"} | Prompts that contract A will call any method of any contract and asks whether to set the signature to Global. | Default or Global according to the user's decision           | Determined by the user      |
 
 ## Invoking a contract with wallets/dAPIs
 

diff --git a/docs/n3/develop/write/1_dotnet.md b/docs/n3/develop/write/1_dotnet.md
@@ -22,7 +22,7 @@ This document covers the usage of project templates and the compiler. For furthe
 
 ## Neo.SmartContract.Template
 
-Neo.SmartContract.Template is a project template used when developing Neo smart contracts. After installing the template, you can create a Neo smart contract project using either the Terminal or Visual Studio.
+[Neo.SmartContract.Template](https://www.nuget.org/packages/Neo.SmartContract.Template) is a project template used when developing Neo smart contracts. After installing the template, you can create a Neo smart contract project using either the Terminal or Visual Studio.
 
 ### Install the template
 
@@ -36,7 +36,7 @@ dotnet new install Neo.SmartContract.Template
 dotnet new list
 ```
 
- There are three default templates available after installing Neo.SmartContract: 
+ There are three default templates available after installing [Neo.SmartContract.Template](https://www.nuget.org/packages/Neo.SmartContract.Template): 
 
 - neocontractowner - Standard contract template with Owner, including GetOwner and SetOwner methods)
 

diff --git a/docs/n3/develop/write/manifest.md b/docs/n3/develop/write/manifest.md
@@ -32,7 +32,7 @@ The Manifest file includes the following fields.
 | Groups             | ContractGroup[] Consisting of a public key and a signature on the contract hash | Defines a group of trusted contracts. Contracts in a group trusts each other and can be invoked by each other,  without prompting the user any warnings. For example, a series of contracts that call each other for a DeFi project. A group is identified by a public key and must has a signature for the contract hash to prove that the contract is included in the group. |
 | SupportedStandards | string[]                                                     | Supported NEP standard, equivalent to NEP-10 in Neo Legacy.x      |
 | Abi                | ContractAbi                                                  | NEP-14 (NeoContract ABI) Description of smart contract methods (name, parameters, return value, offset, safe or not), events (name, parameters) |
-| Permissions        | ContractPermission[] Consisting of the contract and its method names | This field is an array containing a permission object, which defines other contracts and methods that the contract wants to call. The contract can be ScriptHash, Group, or wildcard \*. The method is the method name or wildcard \*. Contracts or methods not declared in the manifest cannot be called by the contract. |
-| Trusts             | WildcardContainer<UInt160\>                                  | Defines other contracts trusted by the contract. The contract can be ScriptHash, Group, or wildcard *. If a contract is trusted, the user will not receive any warning message when the contract is called. |
+| Permissions        | ContractPermission[] Consisting of the contract and its method names | This field is an array containing a permission object, which defines other contracts and methods that the contract wants to call. The contract can be ScriptHash, Group, or Permission.Any \*. The method is the method name or Permission.Any \*. Contracts or methods not declared in the manifest cannot be called by the contract. |
+| Trusts             | WildcardContainer<ContractPermissionDescriptor\>                                  | Defines other contracts trusted by the contract. The contract can be ScriptHash, Group, or Permission.Any *. If a contract is trusted, the user will not receive any warning message when the contract is called. |
 | Extra              | object                                                       | Other user-defined data, such as developer, email, URL, contract profile, etc. |
 
diff --git a/docs/n3/develop/write/nep11.md b/docs/n3/develop/write/nep11.md
@@ -155,6 +155,26 @@ The base class `Nep11Token` also provides the following methods and events:
 Compatibility checks will be activated for any contract that includes the `[SupportedStandards("NEP-17")]` or `[SupportedStandards("NEP-11")]` attribute.
 The Compatibility Check reviews method names, parameters, return values, events, and similar elements to ensure they comply with the standard, and alerts about any failures in the check.
 
+### NFT Royalty Standard
+
+To allow developers to receive better royalty benefits from NFTs, it is recommended to implement the Royalty standard in the contract.
+
+The NFT store can query the royalty amount by calling the contract's `RoyaltyInfo` method. At this point, the total NFT transaction price will be the NFT selling price plus the royalty amount.
+
+In this example code, the royalty fee is 1/1000th of the NFT's selling price, rounded down, regardless of the transaction currency. For instance, if the NFT sells for 0.1 GAS, the royalty fee is 0.0001 GAS (10,000 Datoshi). If the NFT sells for 10 NEO, the royalty fee is 0 NEO.
+
+```csharp
+[Safe]
+public static Map<string, object>[] RoyaltyInfo(ByteString tokenId, UInt160 royaltyToken, BigInteger salePrice)
+{
+    ExecutionEngine.Assert(OwnerOf(tokenId) != null, "This TokenId doesn't exist!");
+    var royaltyInfo = new Map<string, object>();
+    royaltyInfo["royaltyRecipient"] = InitialRecipient;
+    royaltyInfo["royaltyAmount"] = salePrice / 1000;
+    return new[] { royaltyInfo };
+}
+```
+
 ## See also
 
 [NEP-11 Proposal](https://github.com/neo-project/proposals/blob/master/nep-11.mediawiki)
@@ -165,3 +185,7 @@ The Compatibility Check reviews method names, parameters, return values, events,
 
 [NeoVerse Document](https://github.com/chenzhitong/neoverse-readme)
 
+[NFT Royalty Standard](https://github.com/neo-project/proposals/blob/master/nep-24.mediawiki)
+
+[NFT Royalty Example](https://github.com/neo-project/neo-devpack-dotnet/blob/master/examples/Example.SmartContract.SampleRoyaltyNEP11Token/SampleRoyaltyNEP11Token.cs)
+
diff --git a/docs/n3/develop/write/nep17.md b/docs/n3/develop/write/nep17.md
@@ -147,7 +147,7 @@ namespace NEP17
     [ContractVersion("0.0.1")]
     [ContractDescription("A sample NEP-17 token")]
     [ContractSourceCode("https://github.com/neo-project/neo-devpack-dotnet/tree/master/examples/")]
-    [ContractPermission(Permission.WildCard, Method.WildCard)]
+    [ContractPermission(Permission.Any, Method.Any)]
     [SupportedStandards(NepStandard.Nep17)]
     public class SampleNep17Token : Nep17Token
     {

diff --git a/docs/n3/gettingstarted/develop.md b/docs/n3/gettingstarted/develop.md
@@ -8,7 +8,7 @@ The following steps are applicable to multiple system platforms, such as Windows
 
 1. Download and install [Visual Studio Code](https://code.visualstudio.com/Download)
 
-2. Download and install [.NET 6.0 SDK](https://dotnet.microsoft.com/download)
+2. Download and install [.NET 8.0 SDK](https://dotnet.microsoft.com/download)
 
 3. Run the command line and enter the following command to check if you have installed SDK successfully. 
 
@@ -20,79 +20,56 @@ The following steps are applicable to multiple system platforms, such as Windows
 
 ## Installing contract template
 
-[Neo3.SmartContract.Templates](https://www.nuget.org/packages/Neo3.SmartContract.Templates/) contains the latest contract compiler and a hello contract template. The latest version is recommended：
+[Neo.SmartContract.Template](https://www.nuget.org/packages/Neo.SmartContract.Template) is a project template used when developing Neo smart contracts. After installing the template, you can create a Neo smart contract project using either the Terminal or Visual Studio.
 
-```powershell
-dotnet new -i Neo3.SmartContract.Templates
-```
-
-## Creating a contract project
-
-1. Create a folder named `Nep17` as the contract project。
-
-2. In the command line go to the `Nep17` path and then enter the command to generate code files based on the template.
-
-   ```powershell
-    dotnet new neo3-contract
-   ```
-
-   You can find the files named by the folder name under `Nep17` directory: Nep17.cs and Nep17.csproj.
-
-   If you want to specify the file name, add the option -n, for example, `dotnet new neo3-contract -n tokenA`.
-
-## Editing NEP17 code
-
-Since many developers are concerned about how to publish their own contract assets on the Neo block chain, now let's proceed with the NEP17 contract development on private chain.
-
-1. Download all the .cs files from [NEP17 Template](https://github.com/neo-project/examples/tree/master/csharp/NEP17) and place them under the  `Nep17` directory.
-
-2. Remove the original Nep17.cs generated by the HelloContract template.
-
-3. Run VS Code and install the C# extension as prompted.
+### Install the template
 
-   ![](assets/extension.png)
+```
+dotnet new install Neo.SmartContract.Template
+```
 
-4. Open the `Nep17` folder to edit the Nep17 template。
+### List all dotnet templates
 
-In comparison with Neo Legacy, the Neo N3 NEP17 sample has the following changes:
+```
+dotnet new list
+```
 
-- Added the customized attributes above the smart contract class
+ These default templates are available after installing [Neo.SmartContract.Template](https://www.nuget.org/packages/Neo.SmartContract.Template): 
 
-  ```
-  [DisplayName("Token Name")] 
-  [ManifestExtra("Author", "Neo")] 
-  [ManifestExtra("Email", "[email protected]")] 
-  [ManifestExtra("Description", "This is a NEP17 example")] 
-  [SupportedStandards("NEP-17")] 
-  [ContractPermission("*", "onNEP17Payment")] 
-  public class NEP17 : SmartContract 
-  …… 
-  ```
+- neocontractowner - Standard contract template with the Owner, including the GetOwner and SetOwner methods.
 
-- Removed the Name method
+- neocontractoracle - A contract template using OracleRequest.
 
-- Added _deploy method, which will be executed immediately after the contract is deployed
+- neocontractnep17 - NEP-17 contract template, including the Mint and Burn methods.
 
-- Added the Update and Destroy methods
+:::note
 
-- All the Crowdsale methods are in the NEP17.Crowdsale.cs file. Developers can choose to use this file if need be.
+The `neocontract` template previously used has been renamed to `neocontractowner`.
 
-- Called the onNEP17Payment method of the recipient in the Transfer method
+:::
 
-- Implemented onNEP17Payment to automatically execute the smart contract when NEP17 assets are received.
+### Create a project using templates with Terminal
 
-- Major changes occurred in smart contract framework. For details refer to [Smart Contract API](../reference/scapi/interop.md)
+```
+dotnet new neocontractnep17 
+```
 
-For more information refer to [NEP-17](../develop/write/nep17.md) .
+The project name defaults to the name of the current directory. You can also specify the project name with `-n, --name <name>`, e.g. `dotnet new neocontractnep17 -n MyFirstContract`.
 
 ## Compiling contract file
 
-Run the following command to build your contract：
+In the Terminal interface, go to the project path and run the following command to build your contract：
 
-```powershell
+```
 dotnet build
 ```
 
+or
+
+```
+nccs
+```
+
 Related contract files are outputted under `bin\sc` path in the contract project directory.
 
 ## See also