Added detailed annotations to the interface.

ERCS/erc-7620.md

@@ -34,27 +34,127 @@ pragma solidity ^0.8.20;
 
 interface IERC7620 {
     // Events
-    event ServiceProviderRegistered(address serviceProvider); // Event emitted when a service provider is registered
-    event ServiceProviderDeregistered(address serviceProvider); // Event emitted when a service provider is deregistered
-    event AuthorizationUpdated(address indexed user, address indexed serviceProvider, uint256 newAuthorizedAmount); // Event emitted when authorization amount is updated
-    event FundsDeducted(address indexed user, address indexed serviceProvider, uint256 amount, string referenceId); // Event emitted when funds are deducted
-    event Deposited(address indexed user, uint256 amount); // Event emitted when funds are deposited
-    event AuthorizationRevoked(address indexed user, address indexed serviceProvider); // Event emitted when authorization is revoked
-    event Withdrawal(address indexed user, uint256 amount); // Event emitted when funds are withdrawn
+
+    /**
+     * @dev Event emitted when a service provider is registered.
+     * @param serviceProvider The address of the registered service provider.
+     */
+    event ServiceProviderRegistered(address serviceProvider);
+
+    /**
+     * @dev Event emitted when a service provider is deregistered.
+     * @param serviceProvider The address of the deregistered service provider.
+     */
+    event ServiceProviderDeregistered(address serviceProvider);
+
+    /**
+     * @dev Event emitted when authorization amount is updated.
+     * @param user The address of the user whose authorization is updated.
+     * @param serviceProvider The address of the service provider.
+     * @param newAuthorizedAmount The new authorized amount.
+     */
+    event AuthorizationUpdated(address indexed user, address indexed serviceProvider, uint256 newAuthorizedAmount);
+
+    /**
+     * @dev Event emitted when funds are deducted.
+     * @param user The address of the user from whom funds are deducted.
+     * @param serviceProvider The address of the service provider.
+     * @param amount The amount of funds deducted.
+     * @param referenceId The reference ID associated with the deduction.
+     */
+    event FundsDeducted(address indexed user, address indexed serviceProvider, uint256 amount, string referenceId);
+
+    /**
+     * @dev Event emitted when funds are deposited.
+     * @param user The address of the user who deposited funds.
+     * @param amount The amount of funds deposited.
+     */
+    event Deposited(address indexed user, uint256 amount);
+
+    /**
+     * @dev Event emitted when authorization is revoked.
+     * @param user The address of the user who revoked authorization.
+     * @param serviceProvider The address of the service provider.
+     */
+    event AuthorizationRevoked(address indexed user, address indexed serviceProvider);
+
+    /**
+     * @dev Event emitted when funds are withdrawn.
+     * @param user The address of the user who withdrew funds.
+     * @param amount The amount of funds withdrawn.
+     */
+    event Withdrawal(address indexed user, uint256 amount);
 
     // External functions
-    function registerServiceProvider(address serviceProvider) external; // Registers a new service provider
-    function deregisterServiceProvider(address serviceProvider) external; // Deregisters a service provider
-    function authorizeServiceProvider(address serviceProvider, uint256 amount) external; // Allows users to authorize a service provider to deduct funds
-    function revokeAuthorization(address serviceProvider) external; // Revokes authorization for a service provider to deduct funds
-    function deductAuthorizedFunds(address user, uint256 amount, string calldata referenceId) external; // Deducts funds from the user's pre-authorized amount
-    function deposit(uint256 amount) external; // Allows users to deposit funds into the contract
-    function withdraw(uint256 amount) external; // Allows users to withdraw remaining balance
+
+    /**
+     * @dev Registers a new service provider.
+     * @param serviceProvider The address of the service provider to be registered.
+     */
+    function registerServiceProvider(address serviceProvider) external;
+
+    /**
+     * @dev Deregisters a service provider.
+     * @param serviceProvider The address of the service provider to be deregistered.
+     */
+    function deregisterServiceProvider(address serviceProvider) external;
+
+    /**
+     * @dev Allows users to authorize a service provider to deduct funds.
+     * @param serviceProvider The address of the service provider to authorize.
+     * @param amount The amount of funds to authorize for deduction.
+     */
+    function authorizeServiceProvider(address serviceProvider, uint256 amount) external;
+
+    /**
+     * @dev Revokes authorization for a service provider to deduct funds.
+     * @param serviceProvider The address of the service provider for which authorization is to be revoked.
+     */
+    function revokeAuthorization(address serviceProvider) external;
+
+    /**
+     * @dev Deducts funds from the user's pre-authorized amount.
+     * @param user The address of the user from whom funds will be deducted.
+     * @param amount The amount of funds to deduct.
+     * @param referenceId The reference ID associated with the deduction.
+     */
+    function deductAuthorizedFunds(address user, uint256 amount, string calldata referenceId) external;
+
+    /**
+     * @dev Allows users to deposit funds into the contract.
+     * @param amount The amount of funds to deposit.
+     */
+    function deposit(uint256 amount) external;
+
+    /**
+     * @dev Allows users to withdraw remaining balance.
+     * @param amount The amount of funds to withdraw.
+     */
+    function withdraw(uint256 amount) external;
 
     // View functions
-    function authorizedAmount(address user, address serviceProvider) external view returns (uint256); // Returns the authorized amount for a user and service provider
-    function isServiceProviderRegistered(address serviceProvider) external view returns (bool); // Checks if a service provider is registered
-    function remainingBalance(address user) external view returns (uint256); // Returns the remaining balance for a user
+
+    /**
+     * @dev Returns the authorized amount for a user and service provider.
+     * @param user The address of the user.
+     * @param serviceProvider The address of the service provider.
+     * @return The authorized amount.
+     */
+    function authorizedAmount(address user, address serviceProvider) external view returns (uint256);
+
+    /**
+     * @dev Checks if a service provider is registered.
+     * @param serviceProvider The address of the service provider to check.
+     * @return True if the service provider is registered, otherwise false.
+     */
+    function isServiceProviderRegistered(address serviceProvider) external view returns (bool);
+
+    /**
+     * @dev Returns the remaining balance for a user.
+     * @param user The address of the user.
+     * @return The remaining balance.
+     */
+    function remainingBalance(address user) external view returns (uint256);
 }
 ```
 
@@ -74,4 +174,4 @@ The protocol includes several security measures to ensure the safety of user fun
 
 ## Copyright
 
-Copyright and related rights waived via [CC0](../LICENSE.md).
+Copyright and related rights waived via [CC0](../LICENSE.md).