NEP: 29 Title: Contract deployment/update callback function Author: Roman Khimov <roman@nspcc.ru> Type: Standard Status: Accepted Created: 2024-07-18
This proposal standardizes the callback function that can be implemented by contracts to have some code executed right after initial deployment or update.
Contracts may need to run some initialization/update code right after their deployment or upgrade. Neo N3 has provided a mechanism for that since version 3.0, but it was never properly standardized, so this proposal fixes it.
Neo N3 has a native ContractManagement contract that is used for contract deployment and update via deploy and update methods of it. After settling with the new NEF and manifest both of them will invoke a special _deploy method if it's implemented by the contract.
{
"name": "_deploy",
"safe": false,
"parameters": [
{
"name": "data",
"type": "Any"
},
{
"name": "update",
"type": "Boolean"
}
],
"returntype": "Void"
}
This method will be automatically executed by ContractManagement contract when a contract is first deployed or updated. At this point new contract state is already saved (and it can be called from other code), but Deploy or Update notification is not yet emitted by ContractManagement contract.
The data parameter is completely contract-specific, contracts can accept any valid NEP-14 parameter types and handle them as required. It's the same data that is accepted by deploy and update methods of ContractManagement contract.
update is true when contract is updated via update and it's false on initial deployment via deploy.
This callback is designed to guarantee the first code to be executed in a new/updated contract. Previously contracts could provide methods of their own for doing this, but this either required an additional code in deployment/update transaction script or an additional transaction and some special contract state management (to disable actions before some initialization).
_deploy parameters are made to be generic enough to cover all contract state management cases, it is possible to get additional per-network or per-instance contract data for initialization and updates can be easily differentiated from deployments via update parameter.
Notice that if there are any notifications emitted during _deploy execution they will precede Deploy or Update notifications from ContractManagement. This behavior is historic, it mostly means that we're considering contract to be completely ready after succesful _deploy invocation (it can throw an exception or abort execution as well).