Solidity API

TokenCustody

Manages the custody of ERC-20 tokens in a locked state, under the ownership of a single contract.

Implements ledger management to track token ownership and balances. Tokens remain locked within the contract and can only be transferred or withdrawn by the contract owner, ensuring secure governance, accounting, and ledger management.

attachments

mapping(string => address) attachments

Mapping to track CID attachments and their submitters

AttachmentAdded

event AttachmentAdded(string cid, address submitter)

Logs the content identifier (CID) of the attachment and the address of the submitter.

Triggered when a new attachment is added to the contract.

TokensDeposited

event TokensDeposited(address depositor, address token, uint256 value, uint256 tokenId)

Logs the depositor's address, the token address, the deposited value, and the token ID associated with the deposit.

Triggered when ERC20 tokens are deposited into the contract.

ERC20Withdrawn

event ERC20Withdrawn(address sender, address token, uint256 value, address to)

Logs the sender's address, the token address, the withdrawn value, and the recipient address.

Triggered when ERC20 tokens are withdrawn from the contract.

TokenCustodyInvalidTokenId

error TokenCustodyInvalidTokenId(uint256 value)

Logs the invalid token ID value that caused the error.

Thrown when an invalid token ID is provided.

TokenCustodyTransferFailed

error TokenCustodyTransferFailed(address from, address to, uint256 amount)

Logs the sender's address, the recipient's address, and the amount attempted for transfer.

Thrown when an ERC-20 token transfer fails.

TokenCustodyAttachmentAlreadyAdded

error TokenCustodyAttachmentAlreadyAdded(string cid)

Logs the content identifier (CID) of the duplicate attachment.

Thrown when attempting to add an attachment that already exists.

ERC1155MissingApprovalForAll

error ERC1155MissingApprovalForAll(address operator, address owner)

Indicates that the operator has not been granted setApprovalForAll permissions by the token owner.

Thrown when an operator lacks the required approval to manage the owner's ERC1155 tokens.

InvalidCid

error InvalidCid(string cid)

Indicates that the supplied CID does not conform to the expected format.

Thrown when an invalid/empty CID (Content Identifier) is provided.

constructor

constructor(address _initialOwner, string _erc1155Uri) public

Initializes the TokenCustody contract.

The constructor sets the initial owner of the contract and the URI for the ERC1155 token. It inherits the functionality from ERC1155 to handle token URI management and from Ownable to assign ownership to the specified address.

Parameters

Name	Type	Description
_initialOwner	address	The address that will be set as the initial owner of the contract.
_erc1155Uri	string	The URI for the ERC1155 token to be used for metadata.

deposit

function deposit(uint256 _value, address _token) external

Deposit ERC-20 baseTokens for exchange into the contract and mint corresponding ERC-1155 tokens.

Caller must be the depositor and have approved the contract to spend value amount of the ERC-20 baseTokens.

Parameters

Name	Type	Description
_value	uint256	The amount of baseTokens to deposit. Error: - TokenCustodyTransferFailed: Reverted if the erc-20 token transfer fails. Emits: - TokensDeposited: Emitted upon successful deposit of tokens.
_token	address

withdraw

function withdraw(uint256 id, uint256 value, address to) external

Allows the owner to withdraw ERC-20 tokens by burning ERC-1155 tokens.

_This function burns a specified amount of ERC-1155 tokens and, in return, transfers the equivalent amount of ERC-20 tokens to the specified address.

Requirements:

• The contract must not be paused
• The sender must be owner of the contract
• The transfer must succeed_

Parameters

Name	Type	Description
id	uint256	Token ID to withdraw
value	uint256	Amount to withdraw
to	address	Address to receive the tokens Error: - TokenCustodyTransferFailed: Reverted if the erc-20 token transfer fails. Emits: - ERC20Withdrawn: Emitted upon successful withdrawn of tokens from the contract.

addAttachment

function addAttachment(string cid) external

Adds a new attachment to the contract.

_Adds a new attachment to the contract, associating a content identifier (CID) with the owner

Requirements:

• Only callable by owner
• CID must not already exist_

Parameters

Name	Type	Description
cid	string	Content identifier for the attachment Error: - TokenCustodyAttachmentAlreadyAdded: Reverted if there's an attempt to add an attachment that already exists. Emits: - AttachmentAdded: Emitted upon successful addition of attachment to the contract.

safeTransferFrom

function safeTransferFrom(address from, address to, uint256 id, uint256 value, bytes data) public virtual

Transfers ERC-1155 tokens from one address to another.

_This function overrides the {IERC1155-safeTransferFrom} implementation to include additional checks.

Requirements:

• The caller must be the contract owner.
• The caller must be the from address or have been approved via isApprovedForAll._

Parameters

Name	Type	Description
from	address	The address of the current token holder.
to	address	The address receiving the tokens.
id	uint256	The ID of the ERC-1155 token being transferred.
value	uint256	The amount of tokens to transfer.
data	bytes	Additional data sent along with the call. Error: - ERC1155MissingApprovalForAll: Reverted if the caller is not the from address and lacks the necessary approval.

safeBatchTransferFrom

function safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] values, bytes data) public virtual

Transfers multiple ERC-1155 token types from one address to another in a single transaction.

_This function overrides the {IERC1155-safeBatchTransferFrom} implementation to include additional ownership and approval checks.

Requirements:

• The caller must be the contract owner.
• The caller must be the from address or have been approved via isApprovedForAll.
• ids and values arrays must have the same length._

Parameters

Name	Type	Description
from	address	The address of the current token holder.
to	address	The address receiving the tokens.
ids	uint256[]	An array of token IDs being transferred.
values	uint256[]	An array of amounts for each token ID being transferred.
data	bytes	Additional data sent along with the call. Error: - ERC1155MissingApprovalForAll: Reverted if the caller is not the from address and lacks the necessary approval.

_tokenIdFromAddress

function _tokenIdFromAddress(address token) internal pure returns (uint256)

Computes a unique token ID based on the provided ERC-20 token address.

This function generates a token ID by typecasting the address of an ERC-20 token into a uint256. The address is first cast to uint160, then further cast into uint256 to derive a unique token ID.

Parameters

Name	Type	Description
token	address	The address of the ERC-20 token.

Return Values

Name	Type	Description
[0]	uint256	A unique uint256 token ID derived from the token address.

_uint256ToAddress

function _uint256ToAddress(uint256 value) internal pure returns (address)

Converts a uint256 value to its corresponding Ethereum address.

This function takes a uint256 value and converts it to an address type by typecasting it to uint160, ensuring the value is within the valid range for an Ethereum address.

Parameters

Name	Type	Description
value	uint256	The uint256 value to be converted.

Return Values

Name	Type	Description
[0]	address	address The Ethereum address corresponding to the uint256 value. Error: - TokenCustodyInvalidTokenId: Reverted if the typecasted value exceeds the address range.