Neo N3 Smart Contract Debugger launch.config Reference

Note, this document is for Neo N3 smart contract launch configurations (i.e. .NEF files). For information about Neo Legacy smart contract launch configurations, please see this document.

The Neo Smart Contract Debugger enables fine grained execution control via custom configuration settings in launch.json. This document provides information on these settings.

Remember, the Neo Smart Contract Debugger is in preview. You will find bugs and/or missing functionality as you use it. Please let us know of any issues you find or enhancements you would like to see via our GitHub repo.

program

Absolute path to NEF file being debugged. Contract manifest (aka .manifest.json) and Debug Info (aka .nefbugnfo) expected to be located in the same folder.

Example:

"program": "${workspaceFolder}/token-contract/bin/sc/NeoContributorTokens.nef",

invocation

Describes how the contract will be invoked. Neo N3 debugger supports multiple invocation mechanisms, described below.

invoke operation

With this invocation, the configuration specifies the operation name and arguments to invoke. By default, the debugger generates an invocation script for calling the specified operation with the specified arguments from the contract specified via the program property. Optionally, a different contract may be specified via the contract property. This is particularly useful for debugging OnNep17Payment operations that are invoked as a result of a transfer operation.

"invocation": {
    "operation": "mint",
    "args": [
        "Da Hongfei",
        "Founder of Neo, Chair of Neo Foundation, CEO of NGD",
        "https://neo3.azureedge.net/images/discover/DaHongfei.jpg"
    ]
}

invocation file

With this invocation, the configuration specifies a path to an existing Neo invoke file. Invoke files are JSON format files, similar in structure to the operation invocation described above. Invocation files are supported by both the Neo Smart Contract Debugger as well as by Neo Express.

"invocation": {
    "invoke-file": "${workspaceFolder}/invoke-files/list-nft.neo-invoke.json"
},

trace-file

With this invocation, the configuration specifies a path to an existing .neo-trace file, typically generated by NeoTrace and NeoExpress (via the --trace option). This allows debugging of transactions that executed on a public network such as MainNet or TestNet.

Note, when using a trace file, most of the properties defined in this document are not used. program must still be specified and only sourceFileMap, return-types and stored-contracts optional properties are used. All other properties are ignored.

"invocation": {
    "trace-file": "${workspaceFolder}/trace-files/0x45239b3764a0973c89c1fca6bf1ef438a462f7fb705cdf7cf1739abe48328dad.neo-trace"
}

oracle-response

This invocation configuration is used to debug an oracle response callback method.

Properties for this invocation type include:

url: the url of the oracle results the debugger is simulating. url is a required property of this invocation type.
result: JSON results to pass to the oracle callback operation
result-file: path to a JSON file to pass to the oracle callback operation

Either result or result-file must be specified. If both are specified, result is used and result-file is ignored

code: OracleResponseCode to use for the response. Defaults to Success
callback: contract operation callback to use for synthesized oracle requests
filter: JSONPath filter value to use for synthesized oracle requests
gas: gasForResponse value to use for synthesized oracle requests

Neo Debugger will generate an oracle request for the contract specified in program property using the url, callback, filter and gas properties of the oracle response invocation object if there isn't an existing outstanding request in the specified checkpoint. If there is an existing oracle request for the specified url, the callback, filter and gas properties are ignored.

"invocation": {
    "oracle-response": {
        "url": "https://some-domain.example/some/path",
        "result-file": "${workspaceFolder}/response.json",
    }
},

deploy

This invocation configuration is used to debug the _deploy method of a contract.

"invocation": "deploy",

neo-express

Specifies the path to a NeoExpress file. Specifying this property enables accounts in other launch configuration properties (such as signers and operation args) to reference accounts from the .neo-express file via the @ syntax (aka @alice) instead of requiring a Neo N3 address (aka NViTnvofZYshnqppD6ksCtUzBDn54an5hM) or hex encoded 20 byte array (such as 0xccc907b1d386a52071285e580322a612e508a4f2).

"neo-express": "${workspaceFolder}/default.neo-express",

checkpoint

Specifies the path to a NeoExpress checkpoint file. Specifying this property enables the debugger to use real blockchain data while debugging.

Note, Neo Debugger NEVER updates an actual NeoExpress node instance. Contract storage changes are stored in memory and discarded when the debugging session ends. Each individual launch of the debugger starts from the same initial state.

If this property is not set, Neo Debugger creates a stub Neo Blockchain with only the genesis block. The debugger ensures the contract specified in program is deployed on the chain, but adds no other contract storage information. By specifying a checkpoint, the developer can debug scenarios with representative data stored in an actual instance of a NeoExpress node.

Note, even when checkpoint is specified, the debugger still checks to ensure the latest version of the program contract is deployed. If it is not, the deployed version is updated (in memory, as per earlier note) to the current version on disk. This ensures the developer can always debug the contract as it currently exists on disk in compiled format.

"checkpoint": "${workspaceFolder}/checkpoints/token-bought.neoxp-checkpoint",

signers

For more information about signers / witnesses, please see Thou shalt check their witnesses by the good folks at the NEO SPCC

Every Neo transaction that executes on the blockchain must be signed by one or more accounts. The signers configuration property is used to specify signing information for the transaction executing in the debugger.

signers is an array of JSON encoded signer objects. A signer can be specified as a simple string or as a JSON object that supports additional properties.

Properties for a signers object include:

account specifies a wallet account, as a Neo N3 address (such as NViTnvofZYshnqppD6ksCtUzBDn54an5hM), a hex encoded 20 byte array (such as 0xccc907b1d386a52071285e580322a612e508a4f2) or an @ prefixed NeoExpress wallet name such as @alice. The @ prefixed syntax is only supported if the neo-express property is specified. This property is required. If the default values are sufficient for the other signer properties, the account string can be specified directly.
scopes specifies the WitnessScope of the signer. WitnessScope.CalledByEntry scope is used by default.
allowedcontracts specifies the list of contract hashes allowed by the WitnessScope.CustomContracts scope. Contract hashes can be specified by hex encoded string or deployed contract name.
allowedgroups specifies the list of custom group hex-encoded public keys allowed by the WitnessScope.CustomGroups scope.

Note, at this time WitnessScope.WitnessRules is not supported by the Neo debugger.

If no signers are specified, a single signer with a dummy account value and WitnessScope.None scope is used. The dummy account signer will fail all Runtime.CheckWitness calls unless the check-result config property is specified (see below).

"signers": [ 
    "@alice",
    {
        "account": "@bob",
        "scopes": "Global"
    }
],

deploy-signer

deploy-signer is a signer JSON object as described above that is used when deploying the latest version of the contract to the debugger stub chain. If the latest version of the contract is already deployed, the deploy-signer property is not used

For deploy invocations, the debugger will use the signers value if specified and only use the deploy-signer value as a fallback.

"deploy-signer": "@owen"

runtime

Specifies behavior of Runtime.Trigger and Runtime.CheckWitness members.

Runtime.Trigger returns either TriggerType.Verification or TriggerType.Application. By default, the debugger return TriggerType.Application for Runtime.Trigger, but this can be overridden by the runtime.trigger configuration property.

Note, at this time only TriggerType.Application is supported.

Runtime.CheckWitness takes a Hash160 or Public key parameter and returns a boolean. The result of this call indicates if the specified account has signed the transaction that triggered the current contract execution. By default, Runtime.CheckWitness uses the data in the blockchain and transaction signers as it would on a production node. However, the launch configuration can override this behavior in one of two ways.

The configuration can specify the runtime.witnesses.check-result property as a boolean value that will be returned from Runtime.CheckWitness, regardless of the parameter provided.
The configuration can specify the runtime.witnesses property as an array of hex encoded addresses or public keys. With this approach, Runtime.CheckWitness returns true if the provided parameter matches a value from the specified array

"runtime": {
    "witnesses": {
        "check-result": true
    }
}

stored-contracts

This property specifies a list of paths to other .NEF files that a given launch configuration may interact with. This property enables the debugger to load the debug info for these additional contracts to enable stepping across contract boundaries.

Note, unlike the contract specified in program, the Neo Debugger does NOT ensure the latest version of the stored-contracts are deployed to the stub debug chain. This property is only useful in conjunction with the checkpoint property, assuming the contracts listed in stored-contracts were deployed before the checkpoint was created.

"stored-contracts": [
    "${workspaceFolder}/store-contract/bin/sc/DemoShopContract.nef"
]

storage

Note, use of storage property has largely been replaced with checkpoint. However, it is still supported by the debugger.

Key/value pairs used to populate debugger's emulated storage. Similar to other launch configuration settings, strings prefixed with '0x' are treated as hex-encoded byte arrays.

If a specified key already exists in the checkpoint file, the value specified in the launch configuration takes precedence.

JSON for the storage configuration setting can be generated via the Neo-Express contract storage command by using the --json argument.

Examples:

"storage": [
    {
        "key": "neo.org",
        "value": "Neo Foundation"
    }
],

"storage": [
    {
        "key": "0x8a6f1e4f13022b26e56e957cb8251b082f0748b1007465737361",
        "value": "0x174876e800"
    },
    {
        "key": "0x796c707075536c61746f740074636172746e6f63",
        "value": "0x174876e800"
    },
    {
        "key": "0xd2cbfbe9bec47318113e4d41c95174023851df74d7cb2a9e4049d5c84d2b2a6d006f666e497874",
        "value": "0x174876e80005028a6f1e4f13022b26e56e957cb8251b082f0748b1140000000380"
    },
],

return-types

Specifies the expected return type of the contract entry-point. Particularly useful when the contract entry-point returns a C# object, but the specific operation being invoked returns a strongly-typed value.

Note, it is possible for Neo smart contracts to have multiple return values. Smart contracts compiled from C# always have a single return value, but the configuration property name is plural and the value must be an array.

"return-types": ["bool"],

"return-types": ["string"],

sourceFileMap

Optional source file mappings passed to the debug engine

Example:

"sourceFileMap": {
    "C:\\foo": "/home/user/foo"
}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

debug-config-reference.md

debug-config-reference.md

Neo N3 Smart Contract Debugger launch.config Reference

program

invocation

invoke operation

invocation file

trace-file

oracle-response

deploy

neo-express

checkpoint

signers

deploy-signer

runtime

stored-contracts

storage

return-types

sourceFileMap

Files

debug-config-reference.md

Latest commit

History

debug-config-reference.md

File metadata and controls

Neo N3 Smart Contract Debugger launch.config Reference

program

invocation

invoke operation

invocation file

trace-file

oracle-response

deploy

neo-express

checkpoint

signers

deploy-signer

runtime

stored-contracts

storage

return-types

sourceFileMap