Talking about Witness and Trigger on Neo blockchain

Today we will talk about two very important mechanisms on Neo blockchain, called Witness and Trigger. If haven’t read about how Neo network operates, please take a look before proceeding in this article (3 minutes read): https://medium.com/neoresearch/understanding-neo-network-in-five-pictures-e51b7c19d6e0

When developing Smart Contracts, we usually care about one specific execution mode, called Application Trigger. Remember our Hello World tutorial, it runs on a Trigger called Application, executing the programmed contract instructions AFTER the Transaction has been verified. So, besides executing a Smart Contract, Neo blockchain allows us to program the behavior of a Transaction itself, allowing to to be validated or not, according to some specified rules.

Current existing Triggers are Verification (to verify that current transaction is valid) and Application (to execute a Smart Contract that passed verification). There is a proposal to include more triggers, called NEP-7, which could add two more execution modes, however we leave this discussion to the future. Let’s focus on the existing ones ;)

Meeting characters: YELLOW and BLUE

So, let’s meet our two characters of the day, called YELLOW and BLUE. Each one has an internal contract to validate a public key against a signature, which is the standard contract we use for common user accounts on Wallet software.

Figure 1 — Scripthashes for YELLOW and BLUE

In our first scenario, YELLOW wants to send 15 GAS to BLUE, so it creates Transaction A. This transaction includes all the 20 GAS that YELLOW has in its account, it gives 15 GAS to BLUE and gives back to itself 5 GAS (the “change”). So, the total is correct, but this transaction fails the Verification mode.

Figure 2 — YELLOW sending 15 GAS to BLUE failed on Verification

Why has Tx A failed? The values are correct, but taking assets from YELLOW requires that it signs the transaction (otherwise anyone could spend everyone else’s tokens…).

Introducing the Witness system

So, we need to attach a Witness to this transaction, and this Witness must be precisely YELLOW scripthash. Every Witness is composed by two parts: VerificationScript (which is YELLOW public key script) and InvocationScript (which is YELLOW signature for Tx A matching its own public key).

Figure 3 — YELLOW transfers 15 GAS to BLUE, and includes his own signed Witness

Ok, now the transaction passed the Verification phase (entering network mempool), meaning that eventually it could be included in a block and consolidating this transaction forever on Neo blockchain.

Avoiding Double-Spending

I emphasized the “could be included”, because not all transactions that enter mempool are allowed to be published on a block. Suppose YELLOW is a “smarty guy” and sends its payment of 15 GAS to BLUE to one node (RPC 1), and at the same time it sends another payment to itself to other node (RPC 2) on another transaction. Since the nodes haven’t communicated yet on peer-to-peer, both will accept the transaction and pass the Verification phase. However, when both transaction arrive at the Consensus nodes, only one of them will be valid to avoid double-spendings (suppose Tx B arrives before Tx C, so Tx B will be published on block and Tx C will be rejected).

Figure 4 — YELLOW sends two transactions to two different nodes at the same time, spending the same “money”. Both pass Verification, but only one will be allowed on the block

Introducing a multisig character: YELLOW+BLUE

Now we have another colleague, please meet YELLOW+BLUE. This is a multisig character, where its Verification script consists of requiring two signatures that matches both YELLOW and BLUE public keys. (Note: if you want to dig deeper on Multisig, you can take a look at: https://medium.com/neoresearch/understanding-multisig-on-neo-df9c9c1403b1)

Figure 4 — Multisig account YELLOW+BLUE

Suppose YELLOW+BLUE wants to send 15 GAS to user BLUE, is it complicated? How many Witnesses do you need? A single one. Hopefully the Witness system on Neo is flexible enough to deal with these (and many other) situations in the same way as it was a single-signature account. So, just fill in the Inputs and Outputs, and attach a Witness with the necessary credentials on InvocationScript (two signatures, one for YELLOW and another for BLUE).

Figure 5 — Multisig transfer of 15 GAS from YELLOW+BLUE to BLUE

Network fee

What happens if you miscalculate the Inputs and Outputs on a transaction? For example, if YELLOW takes 20 GAS from itself and sends only 19.5 GAS to itself, the transaction is accepted. What happened to the other 0.5 GAS? It becomes a network fee (to pay for priority on the network).

Figure 6 — Adding a network fee

Who gets this network fee? The ellected nodes that create blocks, also called Consensus Nodes. **There is another type of fee called system fee, that we can discuss in a future article ;) However, this fee does not go to the Consensus Nodes, but it is redistributed to every person that holds a NEO asset.

Time to perform Invocation.

NEP-5 Token Transfers

We have dealt with global asset transfers (such as GAS and NEO), however users may build their own tokens on Neo blockchain. These tokens are programmed smart contracts that perform simple operations, such as storing the token balance for each user and allowing transfers between them.

Ok, how can you know that the user “owns” the tokens? YELLOW will try to transfer 15 tokens (called TKN) to user BLUE. Transaction F won’t pass Verification, because no credentials are given for YELLOW.

Figure 7 — YELLOW sends 15 TKN to BLUE, and transaction fails Verification

So, how to solve this issue? Simple, just add a witness for YELLOW (the same structure used in previous transactions).

Application Trigger

Global assets automatically require the witness to be attached, so now we need to manually inform that a witness is required, using Script Attribute. Note that it passes Verification Trigger (green arrow) and it also executes the code (Application Trigger), returning HALT,BREAK (positive result).

Figure 8 — Token transfer with witness pass Verification, and Application returns HALT,BREAK

Suppose now that YELLOW wants to transfer 150 TKN to BLUE, but it does not have enough funds. In this case, it will pass Verification because YELLOW is authorized by its Witness to spend funds on that account, but when the token smart contract is execution, on Application Trigger, the result will be a failure (FAULT).

Figure 9–YELLOW tries to send 150 TKN, it passes Verification, but it fails on Application (not enough funds)

Final example: token transfer for multisig

Our final example invites our Multisig character back on stage. So, how does it work for Multisig or any other ellaborate account types to do a token transfer? Simple, just attach its Witness. As long as the VerificationScript of the Witness is validated by its corresponding InvocationScript (in this case, adding both signatures from YELLOW and BLUE) the transaction will pass Verification.

Figure 10 — Token transfer for multisig YELLOW+BLUE

Final words. This is not a simple subject, perhaps one of the hardest concepts to fully understand on Neo technology. So if you don’t get it all at once, don’t worry! Take your time, and eventually all the pieces of this amazing technological puzzle will be put together inside your head ;)

See you next time!