From c92ddefe70bc067fc34e549fb939bbc3ffef4ab1 Mon Sep 17 00:00:00 2001
From: Mikhail <16622558+mmv08@users.noreply.github.com>
Date: Thu, 9 Jan 2025 16:57:21 +0100
Subject: [PATCH] Enhance documentation in TokenCallbackHandler with ERC-1820
 registration details (#885)

This PR adds a detailed comment in the TokenCallbackHandler contract,
clarifying the requirement for accounts to register the implementer via
the ERC-1820 interface registry to receive ERC777 tokens. This update
aims to improve clarity and understanding of the token reception
process.

No functional changes were made to the contract logic.
---
 contracts/handler/TokenCallbackHandler.sol | 11 +++++++----
 1 file changed, 7 insertions(+), 4 deletions(-)

diff --git a/contracts/handler/TokenCallbackHandler.sol b/contracts/handler/TokenCallbackHandler.sol
index 4373d2448..4f8bc5557 100644
--- a/contracts/handler/TokenCallbackHandler.sol
+++ b/contracts/handler/TokenCallbackHandler.sol
@@ -13,7 +13,7 @@ import {IERC165} from "../interfaces/IERC165.sol";
 contract TokenCallbackHandler is ERC1155TokenReceiver, ERC777TokensRecipient, ERC721TokenReceiver, IERC165 {
     /**
      * @notice Handles ERC1155 Token callback.
-     * return Standardized onERC1155Received return value.
+     * @return Standardized onERC1155Received return value.
      */
     function onERC1155Received(address, address, uint256, uint256, bytes calldata) external pure override returns (bytes4) {
         return 0xf23a6e61;
@@ -21,7 +21,7 @@ contract TokenCallbackHandler is ERC1155TokenReceiver, ERC777TokensRecipient, ER
 
     /**
      * @notice Handles ERC1155 Token batch callback.
-     * return Standardized onERC1155BatchReceived return value.
+     * @return Standardized onERC1155BatchReceived return value.
      */
     function onERC1155BatchReceived(
         address,
@@ -35,7 +35,7 @@ contract TokenCallbackHandler is ERC1155TokenReceiver, ERC777TokensRecipient, ER
 
     /**
      * @notice Handles ERC721 Token callback.
-     *  return Standardized onERC721Received return value.
+     * @return Standardized onERC721Received return value.
      */
     function onERC721Received(address, address, uint256, bytes calldata) external pure override returns (bytes4) {
         return 0x150b7a02;
@@ -43,7 +43,10 @@ contract TokenCallbackHandler is ERC1155TokenReceiver, ERC777TokensRecipient, ER
 
     /**
      * @notice Handles ERC777 Token callback.
-     * return nothing (not standardized)
+     * @dev Account that wishes to receive the tokens also needs to register the implementer (this contract) via the ERC-1820 interface registry.
+     *      From the standard: "This is done by calling the setInterfaceImplementer function on the ERC-1820 registry with the holder address as
+     *      the address, the keccak256 hash of ERC777TokensSender (0x29ddb589b1fb5fc7cf394961c1adf5f8c6454761adf795e67fe149f658abe895) as the
+     *      interface hash, and the address of the contract implementing the ERC777TokensSender as the implementer."
      */
     function tokensReceived(address, address, address, uint256, bytes calldata, bytes calldata) external pure override {
         // We implement this for completeness, doesn't really have any value