Merge branch 'master' into debug-mode

* master:
  [Framework: Add] Define Standard Enum (neo-project#877)
  Fix: Fix dependency (neo-project#876)
  create seperate test contracts (neo-project#868)
  fix-nep11token (neo-project#874)
  add comments to statements (neo-project#875)

neo-devpack-dotnet.sln

@@ -16,6 +16,12 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "src", "src", "{79389FC0-C62
 EndProject
 Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "tests", "tests", "{D5266066-0AFD-44D5-A83E-2F73668A63C8}"
 EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Neo.Compiler.CSharp.TestContracts", "tests\Neo.Compiler.CSharp.TestContracts\Neo.Compiler.CSharp.TestContracts.csproj", "{8D67DD5A-D683-481F-915E-98683EA38791}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Neo.SmartContract.Framework.TestContracts", "tests\Neo.SmartContract.Framework.TestContracts\Neo.SmartContract.Framework.TestContracts.csproj", "{A372F1D6-51FF-472C-9508-FDAF7E6FEB13}"
+EndProject
+Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Neo.SmartContract.TestEngine", "tests\Neo.SmartContract.TestEngine\Neo.SmartContract.TestEngine.csproj", "{D0153204-6AEF-4D94-B0E1-8124C38C91D4}"
+EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Neo", "neo\src\Neo\Neo.csproj", "{73223FBD-C562-4FA0-9722-C7F1C382A9DE}"
 EndProject
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "Neo.Cryptography.BLS12_381", "neo\src\Neo.Cryptography.BLS12_381\Neo.Cryptography.BLS12_381.csproj", "{D541BCE9-65BC-475B-94E5-19B6BFFF2B8E}"
@@ -52,6 +58,18 @@ Global
 		{93BEC5CC-BAFF-4389-89E7-84AAFF5D495D}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{93BEC5CC-BAFF-4389-89E7-84AAFF5D495D}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{93BEC5CC-BAFF-4389-89E7-84AAFF5D495D}.Release|Any CPU.Build.0 = Release|Any CPU
+		{8D67DD5A-D683-481F-915E-98683EA38791}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{8D67DD5A-D683-481F-915E-98683EA38791}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{8D67DD5A-D683-481F-915E-98683EA38791}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{8D67DD5A-D683-481F-915E-98683EA38791}.Release|Any CPU.Build.0 = Release|Any CPU
+		{A372F1D6-51FF-472C-9508-FDAF7E6FEB13}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{A372F1D6-51FF-472C-9508-FDAF7E6FEB13}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{A372F1D6-51FF-472C-9508-FDAF7E6FEB13}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{A372F1D6-51FF-472C-9508-FDAF7E6FEB13}.Release|Any CPU.Build.0 = Release|Any CPU
+		{D0153204-6AEF-4D94-B0E1-8124C38C91D4}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{D0153204-6AEF-4D94-B0E1-8124C38C91D4}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{D0153204-6AEF-4D94-B0E1-8124C38C91D4}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{D0153204-6AEF-4D94-B0E1-8124C38C91D4}.Release|Any CPU.Build.0 = Release|Any CPU
 		{73223FBD-C562-4FA0-9722-C7F1C382A9DE}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
 		{73223FBD-C562-4FA0-9722-C7F1C382A9DE}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{73223FBD-C562-4FA0-9722-C7F1C382A9DE}.Release|Any CPU.ActiveCfg = Release|Any CPU
@@ -78,10 +96,13 @@ Global
 		{FC0CAF5A-30A7-4857-B1A4-486FAAA39E5A} = {79389FC0-C621-4CEA-AD2B-6074C32E7BCA}
 		{4C6B120B-99B5-4888-B8D5-45031458DD07} = {D5266066-0AFD-44D5-A83E-2F73668A63C8}
 		{93BEC5CC-BAFF-4389-89E7-84AAFF5D495D} = {D5266066-0AFD-44D5-A83E-2F73668A63C8}
+		{8D67DD5A-D683-481F-915E-98683EA38791} = {D5266066-0AFD-44D5-A83E-2F73668A63C8}
+		{A372F1D6-51FF-472C-9508-FDAF7E6FEB13} = {D5266066-0AFD-44D5-A83E-2F73668A63C8}
+		{D0153204-6AEF-4D94-B0E1-8124C38C91D4} = {D5266066-0AFD-44D5-A83E-2F73668A63C8}
 		{73223FBD-C562-4FA0-9722-C7F1C382A9DE} = {49D5873D-7B38-48A5-B853-85146F032091}
-		{35A34EBD-F2BF-4D83-A096-D5F007B12732} = {49D5873D-7B38-48A5-B853-85146F032091}
 		{D541BCE9-65BC-475B-94E5-19B6BFFF2B8E} = {49D5873D-7B38-48A5-B853-85146F032091}
 		{D6D53889-5A10-46A4-BA66-E78B56EC1881} = {49D5873D-7B38-48A5-B853-85146F032091}
+		{35A34EBD-F2BF-4D83-A096-D5F007B12732} = {49D5873D-7B38-48A5-B853-85146F032091}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {6DA935E1-C674-4364-B087-F1B511B79215}

scripts/load_submodule.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+
+# Check if the current directory is a git repository
+if [ ! -d ".git" ]; then
+    echo "Error: This script must be run from the root of a Git repository."
+    exit 1
+fi
+
+# Initialize and update git submodules
+git submodule update --init --recursive
+
+echo "Git submodules have been updated."

src/Neo.Compiler.CSharp/CompilationContext.cs

@@ -30,6 +30,7 @@
 using System.Runtime.CompilerServices;
 using System.Text;
 using System.Xml.Linq;
+using scfx::Neo.SmartContract.Framework.Attributes;
 using Diagnostic = Microsoft.CodeAnalysis.Diagnostic;
 
 namespace Neo.Compiler
@@ -149,7 +150,7 @@ private void Compile()
             }
         }
 
-        internal static CompilationContext Compile(IEnumerable<string> sourceFiles, IEnumerable<MetadataReference> references, Options options)
+        public static CompilationContext Compile(IEnumerable<string> sourceFiles, IEnumerable<MetadataReference> references, Options options)
         {
             IEnumerable<SyntaxTree> syntaxTrees = sourceFiles.OrderBy(p => p).Select(p => CSharpSyntaxTree.ParseText(File.ReadAllText(p), options: options.GetParseOptions(), path: p));
             if (IsSingleAbstractClass(syntaxTrees)) throw new FormatException("The given class is abstract, no valid neo SmartContract found.");
@@ -464,7 +465,16 @@ private void ProcessClass(SemanticModel model, INamedTypeSymbol symbol)
                             trusts.Add(trust);
                             break;
                         case nameof(scfx.Neo.SmartContract.Framework.Attributes.SupportedStandardsAttribute):
-                            supportedStandards.UnionWith(attribute.ConstructorArguments[0].Values.Select(p => (string)p.Value!));
+                            supportedStandards.UnionWith(
+                                attribute.ConstructorArguments[0].Values
+                                    .Select(p => p.Value)
+                                    .Select(p =>
+                                        p is int ip && Enum.IsDefined(typeof(NEPStandard), ip)
+                                            ? ((NEPStandard)ip).ToStandard()
+                                            : p as string
+                                    )
+                                    .Where(v => v != null)! // Ensure null values are not added
+                            );
                             break;
                     }
                 }

src/Neo.Compiler.CSharp/MethodConvert/MethodConvert.cs

@@ -731,62 +731,101 @@ private void ConvertStatement(SemanticModel model, StatementSyntax statement)
         {
             switch (statement)
             {
+                // Converts a block statement, which is a series of statements enclosed in braces.
+                // Example: { int x = 1; Console.WriteLine(x); }
                 case BlockSyntax syntax:
                     ConvertBlockStatement(model, syntax);
                     break;
+                // Converts a break statement, typically used within loops or switch cases.
+                // Example: break;
                 case BreakStatementSyntax syntax:
                     ConvertBreakStatement(syntax);
                     break;
+                // Converts a checked statement, used for arithmetic operations with overflow checking.
+                // Example: checked { int x = int.MaxValue; }
                 case CheckedStatementSyntax syntax:
                     ConvertCheckedStatement(model, syntax);
                     break;
+                // Converts a continue statement, used to skip the current iteration of a loop.
+                // Example: continue;
                 case ContinueStatementSyntax syntax:
                     ConvertContinueStatement(syntax);
                     break;
+                // Converts a do-while loop statement.
+                // Example: do { /* actions */ } while (condition);
                 case DoStatementSyntax syntax:
                     ConvertDoStatement(model, syntax);
                     break;
+                // Converts an empty statement, which is typically just a standalone semicolon.
+                // Example: ;
                 case EmptyStatementSyntax syntax:
                     ConvertEmptyStatement(syntax);
                     break;
+                // Converts an expression statement, which is a statement consisting of a single expression.
+                // Example: Console.WriteLine("Hello");
                 case ExpressionStatementSyntax syntax:
                     ConvertExpressionStatement(model, syntax);
                     break;
+                // Converts a foreach loop statement.
+                // Example: foreach (var item in collection) { /* actions */ }
                 case ForEachStatementSyntax syntax:
                     ConvertForEachStatement(model, syntax);
                     break;
+                // Converts a foreach loop statement with variable declarations.
+                // Example: foreach (var (key, value) in dictionary) { /* actions */ }
                 case ForEachVariableStatementSyntax syntax:
                     ConvertForEachVariableStatement(model, syntax);
                     break;
+                // Converts a for loop statement.
+                // Example: for (int i = 0; i < 10; i++) { /* actions */ }
                 case ForStatementSyntax syntax:
                     ConvertForStatement(model, syntax);
                     break;
+                // Converts a goto statement, used for jumping to a labeled statement.
+                // Example: goto myLabel;
                 case GotoStatementSyntax syntax:
                     ConvertGotoStatement(model, syntax);
                     break;
+                // Converts an if statement, including any else or else if branches.
+                // Example: if (condition) { /* actions */ } else { /* actions */ }
                 case IfStatementSyntax syntax:
                     ConvertIfStatement(model, syntax);
                     break;
+                // Converts a labeled statement, used as a target for goto statements.
+                // Example: myLabel: /* actions */
                 case LabeledStatementSyntax syntax:
                     ConvertLabeledStatement(model, syntax);
                     break;
+                // Converts a local variable declaration statement.
+                // Example: int x = 5;
                 case LocalDeclarationStatementSyntax syntax:
                     ConvertLocalDeclarationStatement(model, syntax);
                     break;
+                // Currently, local function statements are not supported in this context.
                 case LocalFunctionStatementSyntax:
                     break;
+                // Converts a return statement, used to exit a method and optionally return a value.
+                // Example: return x + y;
                 case ReturnStatementSyntax syntax:
                     ConvertReturnStatement(model, syntax);
                     break;
+                // Converts a switch statement, including its cases and default case.
+                // Example: switch (variable) { case 1: /* actions */ break; default: /* actions */
                 case SwitchStatementSyntax syntax:
                     ConvertSwitchStatement(model, syntax);
                     break;
+                // Converts a throw statement, used for exception handling.
+                // Example: throw new Exception("Error");
                 case ThrowStatementSyntax syntax:
                     ConvertThrowStatement(model, syntax);
                     break;
+                // Converts a try-catch-finally statement, used for exception handling.
+                // Example: try { /* actions */ } catch (Exception e) { /* actions */ } finally { /* actions */ }
                 case TryStatementSyntax syntax:
                     ConvertTryStatement(model, syntax);
                     break;
+                // Converts a while loop statement.
+                // Example: while (condition) { /* actions */ }
                 case WhileStatementSyntax syntax:
                     ConvertWhileStatement(model, syntax);
                     break;

src/Neo.Compiler.CSharp/MethodConvert/Statement/BlockStatement.cs

@@ -17,6 +17,31 @@ namespace Neo.Compiler
 {
     partial class MethodConvert
     {
+        /// <summary>
+        /// Converts a block statement to a sequence of instructions. This method is used for parsing
+        /// the syntax of block statements within the context of a semantic model. A block statement
+        /// typically consists of a series of statements enclosed in braces `{}`.
+        /// </summary>
+        /// <param name="model">The semantic model that provides information about the block statement.</param>
+        /// <param name="syntax">The syntax of the block statement to be converted.</param>
+        /// <remarks>
+        /// This method starts by initializing a new list of local symbols for the current block.
+        /// It then iterates through each statement within the block, converting each to the appropriate
+        /// set of instructions. Local symbols are tracked and removed once the block is fully converted.
+        /// </remarks>
+        /// <example>
+        /// Here is an example of a block statement syntax:
+        ///
+        /// <code>
+        /// {
+        ///     string x = "Hello world.";
+        ///     Runtime.Log(x);
+        /// }
+        /// </code>
+        ///
+        /// In this example, the block contains two statements: a variable declaration and
+        /// a method call.
+        /// </example>
         private void ConvertBlockStatement(SemanticModel model, BlockSyntax syntax)
         {
             _blockSymbols.Push(new List<ILocalSymbol>());

src/Neo.Compiler.CSharp/MethodConvert/Statement/BreakStatement.cs

@@ -15,6 +15,32 @@ namespace Neo.Compiler
 {
     partial class MethodConvert
     {
+        /// <summary>
+        /// Converts a break statement into the corresponding jump instruction. This method handles
+        /// the parsing and translation of a break statement within loop or switch constructs, converting
+        /// it to an appropriate jump instruction in the neo vm language.
+        /// </summary>
+        /// <param name="syntax">The syntax of the break statement to be converted.</param>
+        /// <remarks>
+        /// This method determines the target of the break statement based on the current context. If the
+        /// break statement is within a try block with no specific break target, it generates an `ENDTRY_L`
+        /// jump instruction to exit the try block. Otherwise, it generates a `JMP_L` instruction to jump
+        /// to the standard break target. This ensures that break statements behave correctly in both
+        /// normal loops/switches and those within try-catch blocks.
+        /// </remarks>
+        /// <example>
+        /// An example of a break statement syntax in a loop:
+        ///
+        /// <code>
+        /// for (int i = 0; i < 10; i++)
+        /// {
+        ///     if (i == 5)
+        ///         break;
+        /// }
+        /// </code>
+        ///
+        /// In this example, the break statement exits the loop when `i` equals 5.
+        /// </example>
         private void ConvertBreakStatement(BreakStatementSyntax syntax)
         {
             using (InsertSequencePoint(syntax))

src/Neo.Compiler.CSharp/MethodConvert/Statement/CheckedStatement.cs

@@ -16,6 +16,34 @@ namespace Neo.Compiler
 {
     partial class MethodConvert
     {
+        /// <summary>
+        /// Converts a checked statement to the corresponding operations. This method is used for parsing
+        /// the syntax of checked statements within the context of a semantic model. Checked statements
+        /// in C# are used to explicitly enable overflow checking for arithmetic operations and conversions.
+        /// </summary>
+        /// <param name="model">The semantic model that provides information about the checked statement.</param>
+        /// <param name="syntax">The syntax of the checked statement to be converted.</param>
+        /// <remarks>
+        /// This method begins by pushing the current state (checked or unchecked) onto a stack to keep
+        /// track of the context. It then processes the block of code within the checked statement.
+        /// After the block is processed, the previous state is restored by popping from the stack.
+        /// This ensures that arithmetic operations within the block are correctly handled according
+        /// to the overflow checking rules specified by the checked statement.
+        /// </remarks>
+        /// <example>
+        /// Here is an example of a checked statement syntax:
+        ///
+        /// <code>
+        /// checked
+        /// {
+        ///     int x = int.MaxValue;
+        ///     int y = x + 1; // This will cause an overflow exception
+        /// }
+        /// </code>
+        ///
+        /// In this example, arithmetic operations inside the checked block are performed with
+        /// overflow checking enabled.
+        /// </example>
         private void ConvertCheckedStatement(SemanticModel model, CheckedStatementSyntax syntax)
         {
             _checkedStack.Push(syntax.Keyword.IsKind(SyntaxKind.CheckedKeyword));