From 5cad866b0b57bf63b517c7c25a43ecd6a62d80fb Mon Sep 17 00:00:00 2001 From: Hecate2 <2474101468@qq.com> Date: Mon, 30 Dec 2024 23:31:12 +0800 Subject: [PATCH] fill all nef, manifest, debugInfo docs (#1271) * fill all nef, manifest, debugInfo docs * More docs about params --- .../Optimizer/Analysers/BasicBlock.cs | 2 +- .../Analysers/InstructionCoverage.cs | 5 ++- .../Optimizer/Analysers/JumpTarget.cs | 2 +- .../Optimizer/AssetBuilder/AssetBuilder.cs | 13 +++--- .../AssetBuilder/DebugInfoBuilder.cs | 5 ++- .../AssetBuilder/OptimizedScriptBuilder.cs | 14 +++---- .../Optimizer/Strategies/JumpCompresser.cs | 30 ++++++------- .../Optimizer/Strategies/Miscellaneous.cs | 6 +-- .../Optimizer/Strategies/Peephole.cs | 42 +++++++++---------- .../Optimizer/Strategies/Reachability.cs | 6 +-- .../SecurityAnalyzer/CheckWitnessAnalyzer.cs | 6 +-- .../SecurityAnalyzer/ReEntrancyAnalyzer.cs | 6 +-- .../SecurityAnalyzer/UpdateAnalyzer.cs | 2 +- .../SecurityAnalyzer/WriteInTryAnalyzer.cs | 6 +-- 14 files changed, 74 insertions(+), 71 deletions(-) diff --git a/src/Neo.Compiler.CSharp/Optimizer/Analysers/BasicBlock.cs b/src/Neo.Compiler.CSharp/Optimizer/Analysers/BasicBlock.cs index 5c75f8288..0413cdd8d 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/Analysers/BasicBlock.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/Analysers/BasicBlock.cs @@ -167,7 +167,7 @@ public HashSet BlocksCoveredFromAddr(int entryAddr, bool includeCall /// /// Get the set of addresses covered by the input set of BasicBlocks /// - /// + /// Basic blocks that composes the whole contract /// public static HashSet AddrCoveredByBlocks(IEnumerable blocks) { diff --git a/src/Neo.Compiler.CSharp/Optimizer/Analysers/InstructionCoverage.cs b/src/Neo.Compiler.CSharp/Optimizer/Analysers/InstructionCoverage.cs index efbe51c75..6fd146dc4 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/Analysers/InstructionCoverage.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/Analysers/InstructionCoverage.cs @@ -189,8 +189,9 @@ public BranchType HandleAbort(int entranceAddr, int abortFromAddr, Stack /// Starting address of script. Should start at a basic block - /// - /// + /// try-catch-finally stack + /// Specify the previous basic block entrance address, if we continue execution from the previous basic block + /// Specify the entrance address of the basic block as the source of jump, if we jumped to current address from that basic block /// Whether it is possible to return without exception /// /// diff --git a/src/Neo.Compiler.CSharp/Optimizer/Analysers/JumpTarget.cs b/src/Neo.Compiler.CSharp/Optimizer/Analysers/JumpTarget.cs index f147cccb4..f5cb5168b 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/Analysers/JumpTarget.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/Analysers/JumpTarget.cs @@ -96,7 +96,7 @@ public static ( public static ( Dictionary, // jump source to target Dictionary, // try source to targets - Dictionary> // target to source + Dictionary> // all jump and try targets to sources ) FindAllJumpAndTrySourceToTargets(List<(int, Instruction)> addressAndInstructionsList, bool includePUSHA = true) { diff --git a/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/AssetBuilder.cs b/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/AssetBuilder.cs index d7d62a495..64fe575ea 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/AssetBuilder.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/AssetBuilder.cs @@ -13,13 +13,14 @@ public static class AssetBuilder /// That means you should get the Instructions from the same initial source. /// Do not script.EnumerateInstructions for many times. /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// new Instruction => int address - /// - /// - /// + /// All jumping instructions source => target + /// All try instructions source => target + /// old int address => Instruction + /// old int address => new int address /// public static (NefFile, ContractManifest, JObject?) BuildOptimizedAssets( NefFile nef, ContractManifest manifest, JObject? debugInfo, diff --git a/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/DebugInfoBuilder.cs b/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/DebugInfoBuilder.cs index 8f83f9af3..170a7c31b 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/DebugInfoBuilder.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/DebugInfoBuilder.cs @@ -14,9 +14,10 @@ static class DebugInfoBuilder /// /// Modify debug info to fit simplified instructions /// - /// + /// Debug information /// new Instruction => int address - /// + /// old int address => Instruction + /// old int address => new int address /// public static JObject? ModifyDebugInfo(JObject? debugInfo, System.Collections.Specialized.OrderedDictionary simplifiedInstructionsToAddress, diff --git a/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/OptimizedScriptBuilder.cs b/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/OptimizedScriptBuilder.cs index b32992cbe..98acb78d6 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/OptimizedScriptBuilder.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/AssetBuilder/OptimizedScriptBuilder.cs @@ -14,8 +14,8 @@ static class OptimizedScriptBuilder /// Build script with instruction dictionary and jump /// /// new Instruction => int address - /// - /// + /// All jumping instructions source => target + /// All try instructions source => target /// Used for convenient debugging only /// /// @@ -84,11 +84,11 @@ public static Script BuildScriptWithJumpTargets( /// Typically used when you delete the oldTarget from script /// and the newTarget is the first following instruction undeleted in script /// - /// - /// - /// - /// - /// + /// target instruction in the old script + /// target instruction in the new script + /// All jumping instructions source => target + /// All try instructions source => target + /// All target instructions that are targets of jumps and trys public static void RetargetJump(Instruction oldTarget, Instruction newTarget, Dictionary jumpSourceToTargets, Dictionary trySourceToTargets, diff --git a/src/Neo.Compiler.CSharp/Optimizer/Strategies/JumpCompresser.cs b/src/Neo.Compiler.CSharp/Optimizer/Strategies/JumpCompresser.cs index 02239217a..8273aded1 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/Strategies/JumpCompresser.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/Strategies/JumpCompresser.cs @@ -26,9 +26,9 @@ public static class JumpCompresser /// /// A preparation for operations that may increase contract size. /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// /// [Strategy(Priority = int.MinValue)] // No attribute public static (NefFile, ContractManifest, JObject?) UncompressJump(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -111,9 +111,9 @@ public static (NefFile, ContractManifest, JObject?) UncompressJump(NefFile nef, /// /// Compress _L instructions to short version, if possible /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = int.MinValue)] public static (NefFile, ContractManifest, JObject?) CompressJump(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -242,9 +242,9 @@ public static (NefFile, ContractManifest, JObject?) CompressJump(NefFile nef, Co /// If the removed JMP or JMP_L itself is a jump target, /// re-target to the instruction after the JMP or JMP_L /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = int.MaxValue)] public static (NefFile, ContractManifest, JObject?) RemoveUnnecessaryJumps(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -311,9 +311,9 @@ public static (NefFile, ContractManifest, JObject?) RemoveUnnecessaryJumps(NefFi /// /// If a JMP or JMP_L jumps to a RET, replace the JMP with RET /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = int.MaxValue - 4)] public static (NefFile, ContractManifest, JObject?) ReplaceJumpWithRet(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -369,9 +369,9 @@ public static (NefFile, ContractManifest, JObject?) ReplaceJumpWithRet(NefFile n /// If an unconditional jump targets a conditional jump, DO NOT replace the unconditional jump with a conditional jump to its final destination. THIS IS WRONG. /// This should be executed very early, before /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = int.MaxValue - 8)] public static (NefFile, ContractManifest, JObject?) FoldJump(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) diff --git a/src/Neo.Compiler.CSharp/Optimizer/Strategies/Miscellaneous.cs b/src/Neo.Compiler.CSharp/Optimizer/Strategies/Miscellaneous.cs index fe58a8a51..9e01b8a09 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/Strategies/Miscellaneous.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/Strategies/Miscellaneous.cs @@ -13,9 +13,9 @@ public static class Miscellaneous /// /// If any method token in nef is not utilized by CALLT, remove the method token. /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = int.MinValue)] public static (NefFile, ContractManifest, JObject?) RemoveMethodToken(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) diff --git a/src/Neo.Compiler.CSharp/Optimizer/Strategies/Peephole.cs b/src/Neo.Compiler.CSharp/Optimizer/Strategies/Peephole.cs index d6e52a5d1..8cabfa725 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/Strategies/Peephole.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/Strategies/Peephole.cs @@ -35,9 +35,9 @@ public static class Peephole /// But at runtime we just need PUSH1 STLOC:$index_of_a /// TODO in the future: use symbolic VM to judge multiple instructions between DUP and DROP /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = 1 << 10)] public static (NefFile, ContractManifest, JObject?) RemoveDupDrop(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -96,9 +96,9 @@ public static (NefFile, ContractManifest, JObject?) RemoveDupDrop(NefFile nef, C /// Do not replace PUSH0 EQUAL with NOT, because it cannot handle null /// Do not replace PUSH0 NOTEQUAL with NZ, because it cannot handle null /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = 1 << 9)] public static (NefFile, ContractManifest, JObject?) UseNz(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -179,9 +179,9 @@ public static (NefFile, ContractManifest, JObject?) UseNz(NefFile nef, ContractM /// PUSHNULL EQUAL -> ISNULL /// PUSHNULL NOTEQUAL -> ISNULL NOT /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = 1 << 9)] public static (NefFile, ContractManifest, JObject?) UseIsNull(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -260,9 +260,9 @@ public static (NefFile, ContractManifest, JObject?) UseIsNull(NefFile nef, Contr /// EQUAL NOT -> NOTEQUAL /// NOTEQUAL NOT -> EQUAL /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = 1 << 10)] public static (NefFile, ContractManifest, JObject?) FoldNotInEqual(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -329,9 +329,9 @@ public static (NefFile, ContractManifest, JObject?) FoldNotInEqual(NefFile nef, /// NZ JMPIF -> JMPIF // not applied, because NZ for null throws exception /// NOT JMPIFNOT -> JMPIF /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = 1 << 8)] public static (NefFile, ContractManifest, JObject?) FoldNotInJmp(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -412,9 +412,9 @@ public static (NefFile, ContractManifest, JObject?) FoldNotInJmp(NefFile nef, Co /// and replace LDSFLD with PUSH const. /// This may increase contract size. /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = 1 << 5)] public static (NefFile, ContractManifest, JObject?) InitStaticToConst(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) @@ -588,9 +588,9 @@ public static (NefFile, ContractManifest, JObject?) InitStaticToConst(NefFile ne /// /// Delete unnecessary _initialize method /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// [Strategy(Priority = 1 << 5)] public static (NefFile, ContractManifest, JObject?) RemoveInitialize(NefFile nef, ContractManifest manifest, JObject? debugInfo = null) diff --git a/src/Neo.Compiler.CSharp/Optimizer/Strategies/Reachability.cs b/src/Neo.Compiler.CSharp/Optimizer/Strategies/Reachability.cs index b6642186a..997a66c66 100644 --- a/src/Neo.Compiler.CSharp/Optimizer/Strategies/Reachability.cs +++ b/src/Neo.Compiler.CSharp/Optimizer/Strategies/Reachability.cs @@ -74,9 +74,9 @@ public static Dictionary /// /// RET RET -> RET /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// /// [Strategy(Priority = int.MaxValue - 16)] diff --git a/src/Neo.Compiler.CSharp/SecurityAnalyzer/CheckWitnessAnalyzer.cs b/src/Neo.Compiler.CSharp/SecurityAnalyzer/CheckWitnessAnalyzer.cs index 974f2eb06..05b6db08f 100644 --- a/src/Neo.Compiler.CSharp/SecurityAnalyzer/CheckWitnessAnalyzer.cs +++ b/src/Neo.Compiler.CSharp/SecurityAnalyzer/CheckWitnessAnalyzer.cs @@ -46,9 +46,9 @@ public string GetWarningInfo(bool print = false) /// /// /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information public static CheckWitnessVulnerability AnalyzeCheckWitness (NefFile nef, ContractManifest manifest, JToken? debugInfo = null) { diff --git a/src/Neo.Compiler.CSharp/SecurityAnalyzer/ReEntrancyAnalyzer.cs b/src/Neo.Compiler.CSharp/SecurityAnalyzer/ReEntrancyAnalyzer.cs index 28e29e359..1038167e1 100644 --- a/src/Neo.Compiler.CSharp/SecurityAnalyzer/ReEntrancyAnalyzer.cs +++ b/src/Neo.Compiler.CSharp/SecurityAnalyzer/ReEntrancyAnalyzer.cs @@ -67,9 +67,9 @@ public string GetWarningInfo(bool print = false) /// then B calls another contract C, changing the storage of C, /// finally you call C. /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information public static ReEntrancyVulnerabilityPair AnalyzeSingleContractReEntrancy (NefFile nef, ContractManifest manifest, JToken? debugInfo = null) { diff --git a/src/Neo.Compiler.CSharp/SecurityAnalyzer/UpdateAnalyzer.cs b/src/Neo.Compiler.CSharp/SecurityAnalyzer/UpdateAnalyzer.cs index 0b5c78f84..a76680cd1 100644 --- a/src/Neo.Compiler.CSharp/SecurityAnalyzer/UpdateAnalyzer.cs +++ b/src/Neo.Compiler.CSharp/SecurityAnalyzer/UpdateAnalyzer.cs @@ -16,7 +16,7 @@ public static class UpdateAnalzyer /// /// Nef file /// Manifest - /// Debug infromation + /// Debug information /// whether it is possible to update the contract. May be wrong. public static bool AnalyzeUpdate (NefFile nef, ContractManifest manifest, JToken? debugInfo = null) diff --git a/src/Neo.Compiler.CSharp/SecurityAnalyzer/WriteInTryAnalyzer.cs b/src/Neo.Compiler.CSharp/SecurityAnalyzer/WriteInTryAnalyzer.cs index 8639a1d61..62c212183 100644 --- a/src/Neo.Compiler.CSharp/SecurityAnalyzer/WriteInTryAnalyzer.cs +++ b/src/Neo.Compiler.CSharp/SecurityAnalyzer/WriteInTryAnalyzer.cs @@ -58,9 +58,9 @@ public string GetWarningInfo(bool print = false) /// But it is ambiguous whether a write in try is actually reverted. /// You can still abort or throw exception when you catch an exception from try. This is safe. /// - /// - /// - /// + /// Nef file + /// Manifest + /// Debug information /// list of addresses that write in try public static WriteInTryVulnerability AnalyzeWriteInTry (NefFile nef, ContractManifest manifest, JToken? debugInfo = null)