*: new NEPs describing onNEPXXPayment callbacks

Signed-off-by: Roman Khimov <[email protected]>
neo-project · Mar 7, 2024 · 6ce5d47 · 6ce5d47
1 parent 90686c5
commit 6ce5d47
Show file tree

Hide file tree

Showing 2 changed files with 190 additions and 0 deletions.
diff --git a/nep-Y.mediawiki b/nep-Y.mediawiki
@@ -0,0 +1,98 @@
+<pre>
+  NEP: <to be assigned>
+  Title: Smart contract transfer callback for non-fungible tokens
+  Author: Erik Zhang <[email protected]>, Roman Khimov <[email protected]>
+  Type: Informational
+  Status: Draft
+  Created: 2024-03-03
+  Requires: 11
+</pre>
+
+==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 <code>supportedstandards</code>
+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 <code>onNEP11Payment</code> method with the following signature:
+
+<pre>
+{
+  "name": "onNEP11Payment",
+  "parameters": [
+    {
+      "name": "from",
+      "type": "Hash160"
+    },
+    {
+      "name": "amount",
+      "type": "Integer"
+    },
+    {
+      "name": "tokenId",
+      "type": "ByteString"
+    },
+    {
+      "name": "data",
+      "type": "Any"
+    }
+  ],
+  "returntype": "Void"
+}
+</pre>
+
+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 <code>System.Runtime.GetCallingScriptHash</code>
+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.
+
+<code>from</code> parameter specifies the sender of tokens and can be <code>null</code>
+for minted tokens.
+
+<code>amount</amount> is the amount of tokens transferred to the contract. It's
+always 1 for non-divisible [[nep-11.mediawiki|NEP-11]] tokens.
+
+<code>tokenId</amount> is the transferred token ID.
+
+<code>data</data> is the same <code>data</code>parameter that was given to the
+[[nep-11.mediawiki|NEP-11]] <code>transfer</code> call. Contract can interpret
+it in any application-specific way including imposing any restrictions on
+accepted <code>data</data> contents.
+
+If the contract implementing this NEP can't accept the transfer (for reasons like
+unexpected token, wrong amount, forbidden sender, wrong <code>data</code>
+parameter or any other) it MUST call <code>ABORT</code> or <code>ABORTMSG</code>
+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 <code>ABORTMSG</code> 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
@@ -0,0 +1,92 @@
+<pre>
+  NEP: <to be assigned>
+  Title: Smart contract transfer callback for fungible tokens
+  Author: Erik Zhang <[email protected]>, Roman Khimov <[email protected]>
+  Type: Informational
+  Status: Draft
+  Created: 2024-03-03
+  Requires: 17
+</pre>
+
+==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 <code>supportedstandards</code>
+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 <code>onNEP17Payment</code> method with the following signature:
+
+<pre>
+{
+  "name": "onNEP17Payment",
+  "parameters": [
+    {
+      "name": "from",
+      "type": "Hash160"
+    },
+    {
+      "name": "amount",
+      "type": "Integer"
+    },
+    {
+      "name": "data",
+      "type": "Any"
+    }
+  ],
+  "returntype": "Void"
+}
+</pre>
+
+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 <code>System.Runtime.GetCallingScriptHash</code>
+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.
+
+<code>from</code> parameter specifies the sender of tokens and can be <code>null</code>
+for minted tokens.
+
+<code>amount</amount> is the amount of tokens transferred to the contract.
+
+<code>data</data> is the same <code>data</code>parameter that was given to the
+[[nep-17.mediawiki|NEP-17]] <code>transfer</code> call. Contract can interpret
+it in any application-specific way including imposing any restrictions on
+accepted <code>data</data> contents.
+
+If the contract implementing this NEP can't accept the transfer (for reasons like
+unexpected token, wrong amount, forbidden sender, wrong <code>data</code>
+parameter or any other) it MUST call <code>ABORT</code> or <code>ABORTMSG</code>
+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 <code>ABORTMSG</code> 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