# Tokens Interface

The Token Smart Contract interface defines a comprehensive set of functions and events essential for managing and regulating the lifecycle of the token. Below is a detailed breakdown of the interface functions, explaining their purpose, source, and functionality.

**`UpdatedTokenInformation`**

**Event**

**Description**: Emitted when the token information is updated. This includes updates to the token's name, symbol, decimals, version, and onchainID.

```solidity
event UpdatedTokenInformation(
    string indexed _newName, 
    string indexed _newSymbol, 
    uint8 _newDecimals, 
    string _newVersion, 
    address indexed _newOnchainID
);
```

***

**`IdentityRegistryAdded`**

**Event**

**Description**: Emitted when the Identity Registry has been set for the token.

```solidity
event IdentityRegistryAdded(address indexed _identityRegistry);
```

***

**`ComplianceAdded`**

**Event**

**Description**: Emitted when the Compliance contract has been set for the token.

```solidity
event ComplianceAdded(address indexed _compliance);
```

***

**`RecoverySuccess`**

**Event**

**Description**: Emitted when an investor successfully recovers their tokens from a lost wallet to a new wallet.

```solidity
event RecoverySuccess(
    address indexed _lostWallet, 
    address indexed _newWallet, 
    address indexed _investorOnchainID
);
```

***

**`AddressFrozen`**

**Event**

**Description**: Emitted when the wallet of an investor is frozen or unfrozen.

```solidity
event AddressFrozen(
    address indexed _userAddress, 
    bool indexed _isFrozen, 
    address indexed _owner
);
```

***

**`TokensFrozen`**

**Event**

**Description**: Emitted when a certain amount of tokens is frozen on a wallet.

```solidity
event TokensFrozen(
    address indexed _userAddress, 
    uint256 _amount
);
```

***

**`TokensUnfrozen`**

**Event**

**Description**: Emitted when a certain amount of tokens is unfrozen on a wallet.

```solidity
event TokensUnfrozen(
    address indexed _userAddress, 
    uint256 _amount
);
```

***

**`Paused`**

**Event**

**Description**: Emitted when the token contract is paused.

```solidity
event Paused(address _userAddress);
```

***

**`Unpaused`**

**Event**

**Description**: Emitted when the token contract is unpaused.

```solidity
event Unpaused(address _userAddress);
```

***

**`setName`**

**Source**: `IToken`

**Description**: Sets the token name. Only the owner of the token contract can call this function.

```solidity
function setName(string calldata _name) external;
```

***

**`setSymbol`**

**Source**: `IToken`

**Description**: Sets the token symbol. Only the owner of the token contract can call this function.

```solidity
function setSymbol(string calldata _symbol) external;
```

***

**`setOnchainID`**

**Source**: `IToken`

**Description**: Sets the onchain ID of the token. Only the owner of the token contract can call this function.

```solidity
function setOnchainID(address _onchainID) external;
```

***

**`pause`**

**Source**: `IToken`

**Description**: Pauses the token contract, preventing token transfers. Only an agent of the token can call this function.

```solidity
function pause() external;
```

***

**`unpause`**

**Source**: `IToken`

**Description**: Unpauses the token contract, allowing token transfers. Only an agent of the token can call this function.

```solidity
function unpause() external;
```

***

**`setAddressFrozen`**

**Source**: `IToken`

**Description**: Sets the frozen status of a specific address. Only an agent of the token can call this function.

```solidity
function setAddressFrozen(address _userAddress, bool _freeze) external;
```

***

**`freezePartialTokens`**

**Source**: `IToken`

**Description**: Freezes a specific amount of tokens on a given address. Only an agent of the token can call this function.

```solidity
function freezePartialTokens(address _userAddress, uint256 _amount) external;
```

***

**`unfreezePartialTokens`**

**Source**: `IToken`

**Description**: Unfreezes a specific amount of tokens on a given address. Only an agent of the token can call this function.

```solidity
function unfreezePartialTokens(address _userAddress, uint256 _amount) external;
```

***

**`setIdentityRegistry`**

**Source**: `IToken`

**Description**: Sets the Identity Registry for the token. Only the owner of the token contract can call this function.

```solidity
function setIdentityRegistry(address _identityRegistry) external;
```

***

**`setCompliance`**

**Source**: `IToken`

**Description**: Sets the Compliance contract for the token. Only the owner of the token contract can call this function.

```solidity
function setCompliance(address _compliance) external;
```

***

**`forcedTransfer`**

**Source**: `IToken`

**Description**: Forces a transfer of tokens between two whitelisted addresses. Only an agent of the token can call this function.

```solidity
function forcedTransfer(
    address _from,
    address _to,
    uint256 _amount
) external returns (bool);
```

***

**`mint`**

**Source**: `IToken`

**Description**: Mints new tokens to a verified address. Only an agent of the token can call this function.

```solidity
function mint(address _to, uint256 _amount) external;
```

***

**`burn`**

**Source**: `IToken`

**Description**: Burns tokens from a specified address. Only an agent of the token can call this function.

```solidity
function burn(address _userAddress, uint256 _amount) external;
```

***

**`recoveryAddress`**

**Source**: `IToken`

**Description**: Recovers tokens from a lost wallet to a new wallet for an investor. Only an agent of the token can call this function.

```solidity
function recoveryAddress(
    address _lostWallet,
    address _newWallet,
    address _investorOnchainID
) external returns (bool);
```

***

**`batchTransfer`**

**Source**: `IToken`

**Description**: Transfers tokens in batch to multiple addresses.

```solidity
function batchTransfer(address[] calldata _toList, uint256[] calldata _amounts) external;
```

***

**`batchForcedTransfer`**

**Source**: `IToken`

**Description**: Forces transfers of tokens in batch between multiple pairs of addresses. Only an agent of the token can call this function.

```solidity
function batchForcedTransfer(
    address[] calldata _fromList,
    address[] calldata _toList,
    uint256[] calldata _amounts
) external;
```

***

**`batchMint`**

**Source**: `IToken`

**Description**: Mints tokens in batch to multiple addresses. Only an agent of the token can call this function.

```solidity
function batchMint(address[] calldata _toList, uint256[] calldata _amounts) external;
```

***

**`batchBurn`**

**Source**: `IToken`

**Description**: Burns tokens in batch from multiple addresses. Only an agent of the token can call this function.

```solidity
function batchBurn(address[] calldata _userAddresses, uint256[] calldata _amounts) external;
```

***

**`batchSetAddressFrozen`**

**Source**: `IToken`

**Description**: Sets the frozen status of multiple addresses in batch. Only an agent of the token can call this function.

```solidity
function batchSetAddressFrozen(address[] calldata _userAddresses, bool[] calldata _freeze) external;
```

***

**`batchFreezePartialTokens`**

**Source**: `IToken`

**Description**: Freezes tokens partially in batch for multiple addresses. Only an agent of the token can call this function.

```solidity
function batchFreezePartialTokens(address[] calldata _userAddresses, uint256[] calldata _amounts) external;
```

***

**`batchUnfreezePartialTokens`**

**Source**: `IToken`

**Description**: Unfreezes tokens partially in batch for multiple addresses. Only an agent of the token can call this function.

```solidity
function batchUnfreezePartialTokens(address[] calldata _userAddresses, uint256[] calldata _amounts) external;
```

***

#### ERC20 Functions

**`Transfer`**

**Event**

**Description**: Emitted when `value` tokens are moved from one account (`from`) to another (`to`).

```solidity
event Transfer(address indexed from, address indexed to, uint256 value);
```

***

**`Approval`**

**Event**

**Description**: Emitted when the allowance of a `spender` for an `owner` is set by a call to `approve`. `value` is the new allowance.

```solidity
event Approval(address indexed owner, address indexed spender, uint256 value);
```

***

**`totalSupply`**

**Source**: `IERC20`

**Description**: Returns the total supply of tokens in existence.

```solidity
function totalSupply() external view returns (uint256);
```

***

**`balanceOf`**

**Source**: `IERC20`

**Description**:

Returns the amount of tokens owned by a specific account.

```solidity
function balanceOf(address account) external view returns (uint256);
```

***

**`transfer`**

**Source**: `IERC20`

**Description**: Moves `amount` tokens from the caller's account to a specified address.

```solidity
function transfer(address to, uint256 amount) external returns (bool);
```

***

**`allowance`**

**Source**: `IERC20`

**Description**: Returns the remaining number of tokens that `spender` is allowed to spend on behalf of `owner` through `transferFrom`.

```solidity
function allowance(address owner, address spender) external view returns (uint256);
```

***

**`approve`**

**Source**: `IERC20`

**Description**: Sets `amount` as the allowance of `spender` over the caller's tokens.

```solidity
function approve(address spender, uint256 amount) external returns (bool);
```

***

**`transferFrom`**

**Source**: `IERC20`

**Description**: Moves `amount` tokens from `from` to `to` using the allowance mechanism. `amount` is then deducted from the caller's allowance.

```solidity
function transferFrom(address from, address to, uint256 amount) external returns (bool);
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.erc3643.org/erc-3643/smart-contracts-library/permissioned-tokens/tokens-interface.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.