Update ERC-7573: ERC-7573 decryption oracle contracts and n-dvp documentation / fix (0.6.0)

Merged by EIP-Bot.

Author: cfries

ERCS/erc-7573.md

@@ -24,6 +24,11 @@ One smart contract implements the `ILockingContract` interface on one chain (e.g
 The smart contract implementing `ILockingContract` locks a token (e.g., the asset) on its chain until a key is presented to encrypt to one of two given values.
 The smart contract implementing `IDecryptionContract`, decrypts one of two keys (via the decryption oracle) conditional to the success or failure of the token transfer (e.g., the payment). A stateless decryption oracle is attached to the chain running `IDecryptionContract` for the decryption.
 
+In addtion there are to interface that standardize the communication with external decryption oracle(s).
+
+The interface`IDecryptionOracle.sol` is implemented by a decryption oracle proxy contract.
+The interface `IDecryptionOracleCallback.sol` has to be implemented by a callback receiving the decrypted key.
+
 ## Motivation
 
 Within the domain of financial transactions and distributed ledger technology (DLT), the Hash-Linked Contract (HLC) concept has been recognized as valuable and has been thoroughly investigated.
@@ -47,7 +52,7 @@ documentation [`ILockingContract.sol`](../assets/eip-7573/contracts/ILockingCont
 ##### Initiation of Transfer: `inceptTransfer`
 
 ```solidity
-function inceptTransfer(uint256 id, int amount, address from, string keyHashedSeller, string memory keyEncryptedSeller) external;
+function inceptTransfer(uint256 id, int amount, address from, bytes keyHashedSeller, bytes memory keyEncryptedSeller) external;
 ```
 
 Called from the buyer of the token to initiate token transfer. Emits a `TransferIncepted` event.
@@ -59,7 +64,7 @@ It is possible to implement the protocol in a way where the hashing method agree
 ##### Initiation of Transfer: `confirmTransfer`
 
 ```solidity
-function confirmTransfer(uint256 id, int amount, address to, string keyHashedBuyer, string memory keyEncryptedBuyer) external;
+function confirmTransfer(uint256 id, int amount, address to, bytes keyHashedBuyer, bytes memory keyEncryptedBuyer) external;
 ```
 
 Called from the seller of the token to confirm token transfer. Emits a `TransferConfirmed` event.
@@ -75,7 +80,7 @@ of tokens is locked (transferred from `from` to the smart contract) and `Transfe
 ##### Transfer: `transferWithKey`
 
 ```solidity
-function transferWithKey(uint256 id, string memory key) external;
+function transferWithKey(uint256 id, bytes memory key) external;
 ```
 
 Called from either the buyer or the seller of the token
@@ -93,14 +98,14 @@ The interface `ILockingContract`:
 
 ```solidity
 interface ILockingContract {
-    event TransferIncepted(uint256 id, int amount, address from, address to, string keyHashedSeller, string keyEncryptedSeller);
-    event TransferConfirmed(uint256 id, int amount, address from, address to, string keyHashedBuyer, string keyEncryptedBuyer);
-    event TokenClaimed(uint256 id, string key);
-    event TokenReclaimed(uint256 id, string key);
-
-    function inceptTransfer(uint256 id, int amount, address from, string memory keyHashedSeller, string memory keyEncryptedSeller) external;
-    function confirmTransfer(uint256 id, int amount, address to, string memory keyHashedBuyer, string memory keyEncryptedBuyer) external;
-    function transferWithKey(uint256 id, string memory key) external;
+    event TransferIncepted(uint256 id, int amount, address from, address to, bytes keyHashedSeller, bytes keyEncryptedSeller);
+    event TransferConfirmed(uint256 id, int amount, address from, address to, bytes keyHashedBuyer, bytes keyEncryptedBuyer);
+    event TokenClaimed(uint256 id, bytes key);
+    event TokenReclaimed(uint256 id, bytes key);
+
+    function inceptTransfer(uint256 id, int amount, address from, bytes memory keyHashedSeller, bytes memory keyEncryptedSeller) external;
+    function confirmTransfer(uint256 id, int amount, address to, bytes memory keyHashedBuyer, bytes memory keyEncryptedBuyer) external;
+    function transferWithKey(uint256 id, bytes memory key) external;
 }
 ```
 
@@ -113,7 +118,7 @@ documentation [`IDecryptionContract.sol`](../assets/eip-7573/contracts/IDecrypti
 ##### Initiation of Transfer: `inceptTransfer`
 
 ```solidity
-function inceptTransfer(uint256 id, int amount, address from, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
+function inceptTransfer(uint256 id, int amount, address from, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
 ```
 
 Called from the receiver of the amount to initiate payment transfer. Emits a `TransferIncepted`.
@@ -124,7 +129,7 @@ The parameter `keyEncryptedFailure` is an encryption of a key and will be decryp
 ##### Transfer: `transferAndDecrypt`
 
 ```solidity
-function transferAndDecrypt(uint256 id, int amount, address to, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
+function transferAndDecrypt(uint256 id, int amount, address to, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
 ```
 
 Called from the sender of the amount to initiate completion of the payment transfer. Emits a `TransferKeyRequested` with keys depending on completion success.
@@ -138,7 +143,7 @@ do not match a previous call to `inceptTransfer`.
 ##### Cancelation of Transfer: `cancelAndDecrypt`
 
 ```solidity
-function cancelAndDecrypt(uint256 id, address from, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
+function cancelAndDecrypt(uint256 id, address from, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
 ```
 
 Called from the receiver of the amount to cancel payment transfer (cancels the incept transfer).
@@ -152,7 +157,7 @@ then this method emits a `TransferKeyRequested` with the key `keyEncryptedFailur
 ##### Release of ILockingContract Access Key: `releaseKey`
 
 ```solidity
-function releaseKey(uint256 id, string memory key) external;
+function releaseKey(uint256 id, bytes memory key) external;
 ```
 
 Called from the (possibly external) decryption oracle.
@@ -165,14 +170,14 @@ The interface `IDecryptionContract`:
 
 ```solidity
 interface IDecryptionContract {
-    event TransferIncepted(uint256 id, int amount, address from, address to, string keyEncryptedSuccess, string keyEncryptedFailure);
-    event TransferKeyRequested(address sender, uint256 id, string encryptedKey);
-    event TransferKeyReleased(address sender, uint256 id, bool success, string key);
-
-    function inceptTransfer(uint256 id, int amount, address from, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
-    function transferAndDecrypt(uint256 id, int amount, address to, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
-    function cancelAndDecrypt(uint256 id, address from, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
-    function releaseKey(uint256 id, string memory key) external;
+    event TransferIncepted(uint256 id, int amount, address from, address to, bytes keyEncryptedSuccess, bytes keyEncryptedFailure);
+    event TransferKeyRequested(address sender, uint256 id, bytes encryptedKey);
+    event TransferKeyReleased(address sender, uint256 id, bool success, bytes key);
+
+    function inceptTransfer(uint256 id, int amount, address from, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
+    function transferAndDecrypt(uint256 id, int amount, address to, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
+    function cancelAndDecrypt(uint256 id, address from, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
+    function releaseKey(uint256 id, bytes memory key) external;
 }
 ```
 
@@ -255,6 +260,50 @@ A corresponding XML sample is shown below.
 </releaseKey>
 ```
 
+### Multi-Party Delivery versus Payment
+
+#### Locking is a Feature
+
+In Delivery-versus-Payment (DvP) protocols like [ERC-7573](../EIPS/eip-7573.html), at least one token must be locked to ensure atomicity, even if only for a short period during the transaction.
+
+While locking may appear as an inconvenient necessity, it is in fact a feature that becomes valuable in the construction of conditional trades or multi-party DvPs.
+
+If *n* parties wish to perform bilateral transactions atomically, there are *at least* *m := 2 • (n - 1)* transactions, of which *m-1* require locking. The last one can operate directly, and its success or failure decides whether the other locks are released or reverted.
+
+A multi-party delivery versus payment is a valuable trade feature. Consider, for example, the case where counterparty A wishes to buy a token *Y* (e.g., a bond) from counterparty C, but in order to fund this transaction, counterparty A wishes to sell a token *X* (e.g., another bond) to counterparty B. However, A does not want to sell bond *X* if the purchase of *Y* fails. A multi-party DvP allows these two transactions to be bound into a single atomic unit.
+
+While for a two-party DvP with two tokens only one token requires locking—and hence a DvP can be constructed without locking on the cash chain—a three-party DvP with three tokens in general requires the ability to lock all three tokens.
+
+This highlights that locking is not just a constraint, but a required feature to enable advanced and economically meaningful protocols.
+
+#### N-DvP with [ERC-7573](../EIPS/eip-7573.html)
+
+A multi-party DvP can be created elegantly by combining multiple (*n-1*) two-party DvPs, for example based on the [ERC-7573](../EIPS/eip-7573.html) protocol.
+
+The procedure is simple: instead of finalizing the respective two-party DvP by a call to `transferAndDecrypt`, the two-party DvP is first confirmed with a call to `confirm`, leaving the finalization open.
+
+At any time, any party can call `cancelAndDecrypt` to release the failure key and revert all lockings.
+
+Once all parties are linked with their respective two-party DvPs, a single call to `transferAndDecrypt` performs locking of the token implementing the `IDecryptionContract` and releases either the success key on success or the failure key on failure.
+
+##### Initiation and Finalization
+
+The counterparty that initiates the multi-party DvP by making the first call
+to the `IDecryptionContract` is the one that is allowed to finalize it via `transferAndDecrypt`, the other may cancel via `cancelAndDecrypt`.
+
+##### Sequence Diagram
+
+Below we depict the corresponding sequence diagram of a multi-party DvP via [ERC-7573](../EIPS/eip-7573.html).
+Note that the individual DvP may come in two different flavors depending on which counterparty is the receiver of the token on the `IDecryptionContract`.
+
+The diagram depicts a multi-party dvp with n+1 counterparties trading n+1 tokens out of which
+the DvPs are bound by the contract on token 0.
+
+![sequence diagram multi party dvp](../assets/eip-7573/doc/multi-party-dvp.svg)
+
+*Note: The more general case of N counterparties trading
+M tokens is just a special case where we enumerate all combination as new counterparties and new tokens.*
+
 ## Security Considerations
 
 The decryption oracle does not need to be a single trusted entity. Instead, a threshold decryption scheme can be employed, where multiple oracles perform partial decryption, requiring a quorum of them to reconstruct the secret key. This enhances security by mitigating the risk associated with a single point of failure or trust.

assets/erc-7573/README.md

@@ -15,9 +15,18 @@ The smart contract implementing `IDecryptionContract`, decrypts one of two keys
 
 ### Provided Contracts
 
+#### DvP
+
 - `contracts/ILockingContract.sol` - Contract locking transfer with given encrypted keys or hashes.
 - `contracts/IDecryptionContract.sol` - Contract performing conditional upon transfer decryption (possibly based on an external oracle).
 
+#### Decryption Oracle
+
+- `contracts/IDecryptionOracle.sol` - Interface implemented by a decryption oracle proxy contract.
+- `contracts/IDecryptionOracleCallback.sol` - Interface to be implemented by a callback receiving the decrypted key.
+
 ### Documentation
 
-- `doc/DvP-Seq-Diag.png` - Sequence diagram.
+- `doc/DvP-Seq-Diag.png` - Sequence diagram of the DvP
+- `doc/multi-party-dvp.svg` - Sequence diagram of a multi-party-dvp.
+

assets/erc-7573/contracts/IDecryptionContract.sol

@@ -38,15 +38,26 @@ interface IDecryptionContract {
      * @param keyEncryptedSuccess Encryption of the key that is emitted upon success.
      * @param keyEncryptedFailure Encryption of the key that is emitted upon failure.
      */
-    event TransferIncepted(uint256 id, int amount, address from, address to, string keyEncryptedSuccess, string keyEncryptedFailure);
+    event TransferIncepted(uint256 id, int amount, address from, address to, bytes keyEncryptedSuccess, bytes keyEncryptedFailure);
+
+    /**
+     * @dev Emitted when the transfer is confirmed.
+     * @param id the trade identifier of the trade.
+     * @param amount the amount to be transferred.
+     * @param from The address of the sender of the payment.
+     * @param to The address of the receiver of the payment.
+     * @param keyEncryptedSuccess Encryption of the key that is emitted upon success.
+     * @param keyEncryptedFailure Encryption of the key that is emitted upon failure.
+     */
+    event TransferConfirmed(uint256 id, int amount, address from, address to, bytes keyEncryptedSuccess, bytes keyEncryptedFailure);
 
     /**
      * @dev Emitted when a transfer has been performed with a success or failure.
      * @param sender a sender. May provide information of the origin of this request.
      * @param id the trade ID.
      * @param encryptedKey The encrypted key associated with the transaction status.
      */
-    event TransferKeyRequested(address sender, uint256 id, string encryptedKey);
+    event TransferKeyRequested(address sender, uint256 id, bytes encryptedKey);
 
     /**
      * @dev Emitted when the decrypted key has been obtained.
@@ -55,7 +66,7 @@ interface IDecryptionContract {
      * @param success a boolean indicating the status. True: success. False: failure.
      * @param key the decrypted key.
      */
-    event TransferKeyReleased(address sender, uint256 id, bool success, string key);
+    event TransferKeyReleased(address sender, uint256 id, bool success, bytes key);
 
     /*------------------------------------------- FUNCTIONALITY ---------------------------------------------------------------------------------------*/
 
@@ -68,18 +79,27 @@ interface IDecryptionContract {
      * @param keyEncryptedSuccess Encryption of the key that is emitted upon success.
      * @param keyEncryptedFailure Encryption of the key that is emitted upon failure.
      */
-    function inceptTransfer(uint256 id, int amount, address from, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
+    function inceptTransfer(uint256 id, int amount, address from, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
 
     /**
-     * @notice Called from the sender of the amount to initiate completion of the payment transfer.
-     * @dev emits a {TransferKeyRequested} with keys depending on completion success.
+     * @notice Called by the sender of the amount to confirm the payment transfer.
+     * @dev emits a {TransferConfirmed}
      * @param id the trade identifier of the trade.
      * @param amount the amount to be transferred.
      * @param to The address of the receiver of the payment. Note: the sender of the payment (from) is implicitly the message.sender.
      * @param keyEncryptedSuccess Encryption of the key that is emitted upon success.
      * @param keyEncryptedFailure Encryption of the key that is emitted upon failure.
      */
-    function transferAndDecrypt(uint256 id, int amount, address to, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
+    function confirmTransfer(uint256 id, int amount, address to, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
+
+    /**
+     * @notice Called by the sender of (first) confirmTransfer initiate completion of the payment transfer(s).
+     *   Note: In case of a multi party DvP there may be multiple incept/confirm pays.
+     *   In case of single DvP the previous confirmTransfer may directly call transferAndDecrypt.
+     * @dev emits a {TransferKeyRequested} with keys depending on completion success.
+     * @param id the trade identifier of the trade.
+     */
+    function transferAndDecrypt(uint256 id) external;
 
     /**
      * @notice Called from the receiver of the amount to cancel payment transfer (cancels the incept transfer).
@@ -89,13 +109,13 @@ interface IDecryptionContract {
      * @param keyEncryptedSuccess Encryption of the key that is emitted upon success.
      * @param keyEncryptedFailure Encryption of the key that is emitted upon failure.
      */
-    function cancelAndDecrypt(uint256 id, address from, string memory keyEncryptedSuccess, string memory keyEncryptedFailure) external;
+    function cancelAndDecrypt(uint256 id, address from, bytes memory keyEncryptedSuccess, bytes memory keyEncryptedFailure) external;
 
     /*+
      * @notice Called from the (possibly external) decryption oracle.
      * @dev emits a {TransferKeyReleased} (if the call was eligible).
      * @param id the trade identifier of the trade.
      * @param key Decrypted key.
      */
-    function releaseKey(uint256 id, string memory key) external;
+    function releaseKey(uint256 id, bytes memory key) external;
 }