Scoped Witnesses: How to Securely Transfer Assets on Neo 3

Igor Machado
Sep 16, 2019 · 3 min read

Since the MainNet launch of the Neo Blockchain in 2016, the Neo platform has grown tremendously in features, and that trend continues this year with the many innovations being implemented in the next generation Neo platform, Neo 3. This article focuses on the innovative Scoped Witnesses feature that has just recently been merged on GitHub into the master branch, which tracks Neo 3 development. This feature will play an important role for allowing secure asset transfers on Neo 3.

Neo 3 has decided to fully adopt Native NEP-5 Assets (instead of Neo 2 UTXO-Based Global Assets), bringing both improved simplicity and even more powerful Smart Contract capabilities (such as Native Tokens) to the network. To facilitate these improvements a number of responsibilities have to be handled differently in the core execution engine (called ApplicationEngine). One of the tasks for ApplicationEngine is to verify that transactions are correct. This means checking that credentials (called Witnesses) correctly pass and that asset owners are allowed for transfers.

For UTXO-based Global Assets on Neo 2, the Witness verification is made by internal processes that securely guarantee that credentials are correctly passed and if the contract is the sender of funds specified in the transaction, then it shall invoke the contract verification function to allow or deny the transfer. However, in Neo 2, the Smart Contract was not allowed to directly interact with the native assets to issue payment transactions from the smart contract, it could only allow or deny the transaction. On general words, UTXO global assets prevented fluid and automatic payments from being made directly by smart contracts. Neo 3 breaks with this limitation by allowing Native NEP-5 (NEO and GAS) to be naturally handled by Smart Contracts. In Neo 3 the same credentials system manages both Native and non-native (user made) assets. The first step to secure NEP-5 transfers on Neo 3 is to add constraints to the credentials passed. These constraints are called: Witness Scopes.

There are four types of scopes on Neo 3: CalledByEntry, CustomContracts, CustomGroups and Global. Most basic (and secure) Scope is named CalledByEntry, that limits usage of credentials to the most basic level of the transaction script passed. This means that credentials passed with CalledByEntry will only be used in invocations of the script passed by the user, which is 100% safe for all kinds of assets and tokens. The following picture describes this process.

Diagram for CalledByEntry scope. User Transaction attaches Witness A signature, and this can only be used by contracts directly invoked by Entry script (Contract B). If any another contract (invoked by third-party) tries to verify Witness A, it will fail (Contract C).

The opposite of CalledByEntry is a Global scope: allowing credentials to be used widely regardless of specific control. This is still safe on a very closed application, possibly constrained by another Neo 3 innovation: the Manifest System (this will be better discussed in future posts). The other two modes (CustomContracts and CustomGroups) allow for detailed setup of user credentials tied to specific applications (and application groups). This is perfect for games and other situations where a digital asset is required on many different situations during Smart Contract execution, thus establishing very concise and descriptive limits for user credentials.

This text doesn’t intend to go deeper on technical aspects of these features, but we invite interested developers to directly chat with core development team on the project Github related issues, to clarify how this (and other) interesting new features are working together to make Neo next generation a truly amazing blockchain platform.

Thanks Jeff, Grace and all who gave priceless contributions to improving this small, but important text.

Neo Smart Economy

Neo is a non-profit community-driven open-source blockchain project. "Digital assets ➕ Digital identity ➕ Smart contract = Smart economy". Website ➡

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade