From 6ce5d475d138d44f998ab3b51d8e366307d09838 Mon Sep 17 00:00:00 2001 From: Roman Khimov Date: Thu, 7 Mar 2024 18:46:12 +0300 Subject: [PATCH] *: new NEPs describing onNEPXXPayment callbacks Signed-off-by: Roman Khimov --- nep-Y.mediawiki | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ nep-Z.mediawiki | 92 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 190 insertions(+) create mode 100644 nep-Y.mediawiki create mode 100644 nep-Z.mediawiki diff --git a/nep-Y.mediawiki b/nep-Y.mediawiki new file mode 100644 index 00000000..54109188 --- /dev/null +++ b/nep-Y.mediawiki @@ -0,0 +1,98 @@ +
+  NEP: 
+  Title: Smart contract transfer callback for non-fungible tokens
+  Author: Erik Zhang , Roman Khimov 
+  Type: Informational
+  Status: Draft
+  Created: 2024-03-03
+  Requires: 11
+
+ +==Abstract== + +This proposal describes the callback method used by Neo smart contracts to +process transfers of non-fungible [[nep-11.mediawiki|NEP-11]] tokens to their addresses. + +==Motivation== + +While the original [[nep-11.mediawiki|NEP-11]] already defines this method, it +lacks some details relevant specifically to the receiver contract and it doesn't +allow for easy reference. This standard can be used in supportedstandards +section of [[nep-15.mediawiki|NEP-15 manifest]] or in any other situation to +refer to contracts able to receive [[nep-11.mediawiki|NEP-11]] tokens (but not +necessarily being [[nep-11.mediawiki|NEP-11]] themselves). Typical use cases +for this functionality are: depositing/staking (with contract locking and +managing tokens according to some rules) or exchange/minting (contract accepting +transfer to itself, but returning some different token to the sender). + +==Specification== + +Smart contracts that need to receive and own [[nep-11.mediawiki|NEP-11]] tokens +MUST implement onNEP11Payment method with the following signature: + +
+{
+  "name": "onNEP11Payment",
+  "parameters": [
+    {
+      "name": "from",
+      "type": "Hash160"
+    },
+    {
+      "name": "amount",
+      "type": "Integer"
+    },
+    {
+      "name": "tokenId",
+      "type": "ByteString"
+    },
+    {
+      "name": "data",
+      "type": "Any"
+    }
+  ],
+  "returntype": "Void"
+}
+
+ +A contract that doesn't implement this method will not be able to receive +[[nep-11.mediawiki|NEP-11]] tokens (transfers to its address will fail). This +method is called by [[nep-11.mediawiki|NEP-11]] contracts which tokens are being +transferred. A particular token can be obtained via the System.Runtime.GetCallingScriptHash +system call. Contracts SHOULD check for this hash to match their expectations +like allowed/accepted tokens, processing this call means that contract trusts +the caller to implement [[nep-11.mediawiki|NEP-11]] correctly. + +from parameter specifies the sender of tokens and can be null +for minted tokens. + +amount is the amount of tokens transferred to the contract. It's +always 1 for non-divisible [[nep-11.mediawiki|NEP-11]] tokens. + +tokenId is the transferred token ID. + +data is the same dataparameter that was given to the +[[nep-11.mediawiki|NEP-11]] transfer call. Contract can interpret +it in any application-specific way including imposing any restrictions on +accepted data contents. + +If the contract implementing this NEP can't accept the transfer (for reasons like +unexpected token, wrong amount, forbidden sender, wrong data +parameter or any other) it MUST call ABORT or ABORTMSG +VM opcode to fail the transaction. This is the only way to ensure contract +won't own transferred tokens, because the method doesn't return any value +and exceptions can be handled by calling contract. + +==Rationale== + +This NEP just follows and explains [[nep-11.mediawiki|NEP-11]] semantics, no +design decisions made here. + +==Backwards Compatibility== + +This NEP is completely compatible with [[nep-11.mediawiki|NEP-11]], the only +extension is ABORTMSG that didn't exist at the time of +[[nep-11.mediawiki|NEP-11]] creation, but it's the same thing semantically. + +==Implementation== + diff --git a/nep-Z.mediawiki b/nep-Z.mediawiki new file mode 100644 index 00000000..2c2cbb9d --- /dev/null +++ b/nep-Z.mediawiki @@ -0,0 +1,92 @@ +
+  NEP: 
+  Title: Smart contract transfer callback for fungible tokens
+  Author: Erik Zhang , Roman Khimov 
+  Type: Informational
+  Status: Draft
+  Created: 2024-03-03
+  Requires: 17
+
+ +==Abstract== + +This proposal describes the callback method used by Neo smart contracts to +process transfers of fungible [[nep-17.mediawiki|NEP-17]] tokens to their addresses. + +==Motivation== + +While the original [[nep-17.mediawiki|NEP-17]] already defines this method, it +lacks some details relevant specifically to the receiver contract and it doesn't +allow for easy reference. This standard can be used in supportedstandards +section of [[nep-15.mediawiki|NEP-15 manifest]] or in any other situation to +refer to contracts able to receive [[nep-17.mediawiki|NEP-17]] tokens (but not +necessarily being [[nep-17.mediawiki|NEP-17]] themselves). Typical use cases +for this functionality are: depositing/staking (with contract locking and +managing tokens according to some rules) or exchange/minting (contract accepting +transfer to itself, but returning some different token to the sender). + +==Specification== + +Smart contracts that need to receive and own [[nep-17.mediawiki|NEP-17]] tokens +MUST implement onNEP17Payment method with the following signature: + +
+{
+  "name": "onNEP17Payment",
+  "parameters": [
+    {
+      "name": "from",
+      "type": "Hash160"
+    },
+    {
+      "name": "amount",
+      "type": "Integer"
+    },
+    {
+      "name": "data",
+      "type": "Any"
+    }
+  ],
+  "returntype": "Void"
+}
+
+ +A contract that doesn't implement this method will not be able to receive +[[nep-17.mediawiki|NEP-17]] tokens (transfers to its address will fail). This +method is called by [[nep-17.mediawiki|NEP-17]] contracts which tokens are being +transferred. A particular token can be obtained via the System.Runtime.GetCallingScriptHash +system call. Contracts SHOULD check for this hash to match their expectations +like allowed/accepted tokens, processing this call means that contract trusts +the caller to implement [[nep-17.mediawiki|NEP-17]] correctly. + +from parameter specifies the sender of tokens and can be null +for minted tokens. + +amount is the amount of tokens transferred to the contract. + +data is the same dataparameter that was given to the +[[nep-17.mediawiki|NEP-17]] transfer call. Contract can interpret +it in any application-specific way including imposing any restrictions on +accepted data contents. + +If the contract implementing this NEP can't accept the transfer (for reasons like +unexpected token, wrong amount, forbidden sender, wrong data +parameter or any other) it MUST call ABORT or ABORTMSG +VM opcode to fail the transaction. This is the only way to ensure contract +won't own transferred tokens, because the method doesn't return any value +and exceptions can be handled by calling contract. + +==Rationale== + +This NEP just follows and explains [[nep-17.mediawiki|NEP-17]] semantics, no +design decisions made here. + +==Backwards Compatibility== + +This NEP is completely compatible with [[nep-17.mediawiki|NEP-17]], the only +extension is ABORTMSG that didn't exist at the time of +[[nep-17.mediawiki|NEP-17]] creation, but it's the same thing semantically. + +==Implementation== + + * https://github.com/nspcc-dev/neo-go/blob/8d67f17943553740fe4caa31c3e9efcf7921aba2/examples/nft-nd/nft.go#L213