verification — Validation of objects and smart contract invokers

This module describes two validation forms found in the NEO chain.

First we have validation of three verifiable objects, namely: Block, ConsensusPayload and Transaction. These are digitally signed using ECDSA. Validation of these objects is done using a so called witness.

A Witness is a verification script executed by the virtual machine to validate the verifiable object. Validation failure prevents for example that a transaction is included in a block and broad casted to the network. Taking the transaction example further, the witness carries a set of virtual machine opcodes (in its invocation_script) that load the transaction signatures into the internal data structures of the VM. Next, the verification_script, which are also virtual machine opcodes, performs the actual verification and operates on the data previously setup by the invocation script.

A second form of validation can be performed inside a smart contract using the CheckWitness() system call. This can be used to limit certain smart contract functions to a specific user, other smart contract or group.

To give this fine grained control NEO created so called signers and a set of verification scopes. Signers are attached to a transaction in its aptly named signers attribute and are matched according to the rules set by the verification scope. The various verification scopes can be configured using a WitnessScope and are set in the scope attribute of a signer.

Note

While multiple signer’s can be attached to a transaction and thus multiple scopes can be set, only the first signer is looked at to determine the scope to use for CheckWitness().

class neo3.network.payloads.verification.Witness(invocation_script, verification_script)

Bases: neo3.core.serialization.ISerializable, neo3.core.IJson

An executable verification script that validates a verifiable object like a transaction.

deserialize(reader)

Deserialize the object from a binary stream.

Parameters

reader (BinaryReader) – instance.

Return type

None

classmethod deserialize_from_bytes(data)

Parse data into an object instance.

Parameters

data (Union[bytes, bytearray]) – hex escaped bytes.

Return type

~ISerializable_T

Returns

a deserialized instance of the class.

classmethod from_json(json)

Create object from JSON

script_hash()

Get the script hash based on the verification script.

Return type

UInt160

serialize(writer)

Serialize the object into a binary stream.

Parameters

writer (BinaryWriter) – instance.

Return type

None

to_array()

Serialize the object into a bytearray.

Return type

bytes

to_json()

Convert object into json

Return type

dict

invocation_script

A set of VM instructions to setup the stack for verification.

verification_script

A set of VM instructions that does the actual verification. It is expected to set the result stack to a boolean True if validation passed.

class neo3.network.payloads.verification.WitnessScope(value)

Bases: enum.IntFlag

Determine the rules for a smart contract CheckWitness() sys call.

classmethod from_chsarp_name(csharp_name)

Internal helper to parse from C# convention

to_csharp_name()

Internal helper to match C# convention

CALLED_BY_ENTRY = 1

Allow the witness if the current calling script hash equals the entry script hash into the virtual machine. Using this prevents passing CheckWitness() in a smart contract called via another smart contract.

CUSTOM_CONTRACTS = 16

Allow the witness if called from a smart contract that is whitelisted in the signer allowed_contracts attribute.

CUSTOM_GROUPS = 32

Allow the witness if any public key is in the signer allowed_groups attribute is whitelisted in the contracts manifest.groups array.

GLOBAL = 128

Allow the witness in all context. Equal to NEO 2.x’s default behaviour.

NONE = 0

No Contract was witnessed. Only sign the transaction.

class neo3.network.payloads.verification.Signer(account, scope=None, allowed_contracts=None, allowed_groups=None)

Bases: neo3.core.serialization.ISerializable, neo3.core.IJson

A class that specifies who can pass CheckWitness() verifications in a smart contract.

deserialize(reader)

Deserialize the object from a binary stream.

Parameters

reader (BinaryReader) – instance.

Return type

None

classmethod deserialize_from_bytes(data)

Parse data into an object instance.

Parameters

data (Union[bytes, bytearray]) – hex escaped bytes.

Return type

~ISerializable_T

Returns

a deserialized instance of the class.

classmethod from_json(json)

Create object from JSON

serialize(writer)

Serialize the object into a binary stream.

Parameters

writer (BinaryWriter) – instance.

Return type

None

to_array()

Serialize the object into a bytearray.

Return type

bytes

to_json()

Convert object into json

Return type

dict

MAX_SUB_ITEMS = 16

Maximum number of allowed_contracts or allowed_groups

account

The TX sender.

allowed_contracts

Whitelist of contract script hashes if used with CUSTOM_CONTRACTS.

Type

List[types.UInt160]

allowed_groups

Whitelist of public keys if used with CUSTOM_GROUPS.

Type

List[cryptography.ECPoint]

scope

The configured validation scope.

Type

payloads.WitnessScope