diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/Erc721Bridge.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/Erc721Bridge.md new file mode 100644 index 00000000000..a01a75bb27c --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/Erc721Bridge.md @@ -0,0 +1,245 @@ +--- +title: Erc721Bridge +--- + +## Erc721Bridge + +This contract is an ERC-721 token bridge contract which is deployed on both L1 and L2. +which calls the library implementations. See _IErc721Bridge_ for more details. + +_The code hash for the same address on L1 and L2 may be different._ + +### MessageStatusChanged + +```solidity +event MessageStatusChanged(bytes32 msgHash, enum LibErc721BridgeStatus.MessageStatus status, address transactor) +``` + +### DestChainEnabled + +```solidity +event DestChainEnabled(uint256 chainId, bool enabled) +``` + +### init + +```solidity +function init(address _addressManager) external +``` + +Initializer to be called after being deployed behind a proxy. + +_Initializer function to setup the EssentialContract._ + +#### Parameters + +| Name | Type | Description | +| ---------------- | ------- | ------------------------------------------- | +| \_addressManager | address | The address of the AddressManager contract. | + +### sendMessageErc721 + +```solidity +function sendMessageErc721(struct IErc721Bridge.Message message) external payable returns (bytes32 msgHash) +``` + +Sends a message from the current chain to the destination chain specified +in the message. + +_Sends a message by calling the LibErc721BridgeSend.sendMessageErc721 library +function._ + +#### Parameters + +| Name | Type | Description | +| ------- | ---------------------------- | ---------------------------------- | +| message | struct IErc721Bridge.Message | The message to send. (See IBridge) | + +#### Return Values + +| Name | Type | Description | +| ------- | ------- | -------------------------------------- | +| msgHash | bytes32 | The hash of the message that was sent. | + +### releaseTokenErc721 + +```solidity +function releaseTokenErc721(struct IErc721Bridge.Message message, bytes proof) external +``` + +Releases the Ether locked in the bridge as part of a cross-chain +transfer. + +_Releases the Ether by calling the LibBridgeRelease.releaseEther +library function._ + +#### Parameters + +| Name | Type | Description | +| ------- | ---------------------------- | ----------------------------------------------------------------------- | +| message | struct IErc721Bridge.Message | The message containing the details of the Ether transfer. (See IBridge) | +| proof | bytes | The proof of the cross-chain transfer. | + +### isMessageSentErc721 + +```solidity +function isMessageSentErc721(bytes32 msgHash) public view virtual returns (bool) +``` + +Check if the message with the given hash has been sent. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------------------ | +| msgHash | bytes32 | The hash of the message. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------------------------------------------------------- | +| [0] | bool | Returns true if the message has been sent, false otherwise. | + +### isMessageReceivedErc721 + +```solidity +function isMessageReceivedErc721(bytes32 msgHash, uint256 srcChainId, bytes proof) public view virtual returns (bool) +``` + +Check if the message with the given hash has been received. + +#### Parameters + +| Name | Type | Description | +| ---------- | ------- | ----------------------------- | +| msgHash | bytes32 | The hash of the message. | +| srcChainId | uint256 | The source chain ID. | +| proof | bytes | The proof of message receipt. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | --------------------------------------------------------------- | +| [0] | bool | Returns true if the message has been received, false otherwise. | + +### isMessageFailedErc721 + +```solidity +function isMessageFailedErc721(bytes32 msgHash, uint256 destChainId, bytes proof) public view virtual returns (bool) +``` + +Check if the message with the given hash has failed. + +#### Parameters + +| Name | Type | Description | +| ----------- | ------- | ----------------------------- | +| msgHash | bytes32 | The hash of the message. | +| destChainId | uint256 | The destination chain ID. | +| proof | bytes | The proof of message failure. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | -------------------------------------------------------- | +| [0] | bool | Returns true if the message has failed, false otherwise. | + +### getMessageStatusErc721 + +```solidity +function getMessageStatusErc721(bytes32 msgHash) public view virtual returns (enum LibErc721BridgeStatus.MessageStatus) +``` + +Get the status of the message with the given hash. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------------------ | +| msgHash | bytes32 | The hash of the message. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---------------------------------------- | ---------------------------------- | +| [0] | enum LibErc721BridgeStatus.MessageStatus | Returns the status of the message. | + +### context + +```solidity +function context() public view returns (struct IErc721Bridge.Context) +``` + +Get the current context + +#### Return Values + +| Name | Type | Description | +| ---- | ---------------------------- | ---------------------------- | +| [0] | struct IErc721Bridge.Context | Returns the current context. | + +### isDestChainEnabled + +```solidity +function isDestChainEnabled(uint256 _chainId) public view returns (bool enabled) +``` + +Check if the destination chain with the given ID is enabled. + +#### Parameters + +| Name | Type | Description | +| --------- | ------- | -------------------- | +| \_chainId | uint256 | The ID of the chain. | + +#### Return Values + +| Name | Type | Description | +| ------- | ---- | ------------------------------------------------------------------ | +| enabled | bool | Returns true if the destination chain is enabled, false otherwise. | + +### hashMessage + +```solidity +function hashMessage(struct IErc721Bridge.Message message) public pure returns (bytes32) +``` + +Compute the hash of a given message. + +#### Parameters + +| Name | Type | Description | +| ------- | ---------------------------- | ------------------------------------ | +| message | struct IErc721Bridge.Message | The message to compute the hash for. | + +#### Return Values + +| Name | Type | Description | +| ---- | ------- | -------------------------------- | +| [0] | bytes32 | Returns the hash of the message. | + +### getMessageStatusSlot + +```solidity +function getMessageStatusSlot(bytes32 msgHash) public pure returns (bytes32) +``` + +Get the slot associated with a given message hash status. + +#### Parameters + +| Name | Type | Description | +| ------- | ------- | ------------------------ | +| msgHash | bytes32 | The hash of the message. | + +#### Return Values + +| Name | Type | Description | +| ---- | ------- | --------------------------------------------------------------- | +| [0] | bytes32 | Returns the slot associated with the given message hash status. | + +--- + +## title: ProxiedErc721Bridge + +## ProxiedErc721Bridge diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/Erc721Vault.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/Erc721Vault.md new file mode 100644 index 00000000000..bd94e743883 --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/Erc721Vault.md @@ -0,0 +1,116 @@ +--- +title: Erc721Vault +--- + +## Erc721Vault + +This contract is for vaulting (and releasing) ERC721 tokens + +_Only the contract owner can authorize or deauthorize addresses._ + +### ContractMapping + +```solidity +struct ContractMapping { + address sisterContract; + string tokenName; + string tokenSymbol; + mapping(uint256 => bool) tokenInVault; +} +``` + +### originalToWrapperData + +```solidity +mapping(address => struct Erc721Vault.ContractMapping) originalToWrapperData +``` + +### Authorized + +```solidity +event Authorized(address addr, bool authorized) +``` + +### TokensReleased + +```solidity +event TokensReleased(address to, address contractAddress, uint256[] tokenIds) +``` + +### onlyAuthorized + +```solidity +modifier onlyAuthorized() +``` + +### init + +```solidity +function init(address addressManager) external +``` + +Initialize the contract with an address manager + +#### Parameters + +| Name | Type | Description | +| -------------- | ------- | ---------------------------------- | +| addressManager | address | The address of the address manager | + +### releaseTokens + +```solidity +function releaseTokens(address recipient, address tokenContract, uint256[] tokenIds) public +``` + +Transfer token(s) from Erc721Vault to a designated address, checking that the +sender is authorized. + +#### Parameters + +| Name | Type | Description | +| ------------- | --------- | ---------------------------- | +| recipient | address | Address to receive Ether. | +| tokenContract | address | Token contract. | +| tokenIds | uint256[] | Array of tokenIds to be sent | + +### authorize + +```solidity +function authorize(address addr, bool authorized) public +``` + +Set the authorized status of an address, only the owner can call this. + +#### Parameters + +| Name | Type | Description | +| ---------- | ------- | ---------------------------------------- | +| addr | address | Address to set the authorized status of. | +| authorized | bool | Authorized status to set. | + +### isAuthorized + +```solidity +function isAuthorized(address addr) public view returns (bool) +``` + +Get the authorized status of an address. + +#### Parameters + +| Name | Type | Description | +| ---- | ------- | ---------------------------------------- | +| addr | address | Address to get the authorized status of. | + +### onERC721Received + +```solidity +function onERC721Received(address, address, uint256, bytes) external pure returns (bytes4) +``` + +--- + +## title: ProxiedErc721Vault + +## ProxiedErc721Vault diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/NftBridgeErrors.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/NftBridgeErrors.md new file mode 100644 index 00000000000..6a68564d272 --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/NftBridgeErrors.md @@ -0,0 +1,59 @@ +--- +title: NftBridgeErrors +--- + +## NftBridgeErrors + +### ERC721_TV_NOT_AUTHORIZED + +```solidity +error ERC721_TV_NOT_AUTHORIZED() +``` + +### ERC721_TV_DO_NOT_BURN + +```solidity +error ERC721_TV_DO_NOT_BURN() +``` + +### ERC721_B_TV_PARAM + +```solidity +error ERC721_B_TV_PARAM() +``` + +### ERC721_B_FORBIDDEN + +```solidity +error ERC721_B_FORBIDDEN() +``` + +### ERC721_B_WRONG_CHAIN_ID + +```solidity +error ERC721_B_WRONG_CHAIN_ID() +``` + +### ERC721_B_STATUS_MISMATCH + +```solidity +error ERC721_B_STATUS_MISMATCH() +``` + +### ERC721_B_SIGNAL_NOT_RECEIVED + +```solidity +error ERC721_B_SIGNAL_NOT_RECEIVED() +``` + +### ERC721_B_OWNER_IS_NULL + +```solidity +error ERC721_B_OWNER_IS_NULL() +``` + +### ERC721_B_WRONG_TO_ADDRESS + +```solidity +error ERC721_B_WRONG_TO_ADDRESS() +``` diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/IErc721Bridge.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/IErc721Bridge.md new file mode 100644 index 00000000000..bfff21613df --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/IErc721Bridge.md @@ -0,0 +1,115 @@ +--- +title: IErc721Bridge +--- + +## IErc721Bridge + +Bridge interface for NFT contracts. + +_Ether is held by Bridges on L1 and by the EtherVault on L2, +not TokenVaults._ + +### Message + +```solidity +struct Message { + uint256 id; + address sender; + uint256 srcChainId; + uint256 destChainId; + address owner; + address to; + address refundAddress; + address tokenContract; + uint256[] tokenIds; + uint256 processingFee; + uint256 gasLimit; + string tokenSymbol; + string tokenName; + string[] tokenURIs; +} +``` + +### Context + +```solidity +struct Context { + bytes32 msgHash; + address sender; + uint256 srcChainId; +} +``` + +### SignalSentErc721 + +```solidity +event SignalSentErc721(address sender, bytes32 msgHash) +``` + +### MessageSentErc721 + +```solidity +event MessageSentErc721(bytes32 msgHash, struct IErc721Bridge.Message message) +``` + +### TokenReleasedErc721 + +```solidity +event TokenReleasedErc721(bytes32 msgHash, address to, address token, uint256 tokenId) +``` + +### sendMessageErc721 + +```solidity +function sendMessageErc721(struct IErc721Bridge.Message message) external payable returns (bytes32 msgHash) +``` + +Sends a message to the destination chain and takes custody +of the token(s) required in this contract. + +### releaseTokenErc721 + +```solidity +function releaseTokenErc721(struct IErc721Bridge.Message message, bytes proof) external +``` + +### isMessageSentErc721 + +```solidity +function isMessageSentErc721(bytes32 msgHash) external view returns (bool) +``` + +Checks if a msgHash has been stored on the bridge contract by the +current address. + +### isMessageReceivedErc721 + +```solidity +function isMessageReceivedErc721(bytes32 msgHash, uint256 srcChainId, bytes proof) external view returns (bool) +``` + +Checks if a msgHash has been received on the destination chain and +sent by the src chain. + +### isMessageFailedErc721 + +```solidity +function isMessageFailedErc721(bytes32 msgHash, uint256 destChainId, bytes proof) external view returns (bool) +``` + +Checks if a msgHash has been failed on the destination chain. + +### context + +```solidity +function context() external view returns (struct IErc721Bridge.Context context) +``` + +Returns the bridge state context. + +### hashMessage + +```solidity +function hashMessage(struct IErc721Bridge.Message message) external pure returns (bytes32) +``` + diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeData.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeData.md new file mode 100644 index 00000000000..1ffd9784e81 --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeData.md @@ -0,0 +1,87 @@ +--- +title: LibErc721BridgeData +--- + +## LibErc721BridgeData + +Stores message metadata on the Bridge. It's used to keep track of the state +of messages that are being +transferred across the bridge, and it contains functions to hash messages and +check their status. + +### State + +_The State struct stores the state of messages in the Bridge +contract._ + +```solidity +struct State { + uint256 nextMessageId; + struct IErc721Bridge.Context ctx; + mapping(bytes32 => bool) tokensReleased; + uint256[45] __gap; +} +``` + +### StatusProof + +_StatusProof holds the block header and proof for a particular +status._ + +```solidity +struct StatusProof { + struct BlockHeader header; + bytes proof; +} +``` + +### MESSAGE_HASH_PLACEHOLDER + +```solidity +bytes32 MESSAGE_HASH_PLACEHOLDER +``` + +### CHAINID_PLACEHOLDER + +```solidity +uint256 CHAINID_PLACEHOLDER +``` + +### SRC_CHAIN_SENDER_PLACEHOLDER + +```solidity +address SRC_CHAIN_SENDER_PLACEHOLDER +``` + +### MessageSentErc721 + +```solidity +event MessageSentErc721(bytes32 msgHash, struct IErc721Bridge.Message message) +``` + +### DestChainEnabledErc721 + +```solidity +event DestChainEnabledErc721(uint256 chainId, bool enabled) +``` + +### hashMessage + +```solidity +function hashMessage(struct IErc721Bridge.Message message) internal pure returns (bytes32) +``` + +Calculate the keccak256 hash of the message + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| message | struct IErc721Bridge.Message | The message to be hashed | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | msgHash The keccak256 hash of the message | + diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeProcess.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeProcess.md new file mode 100644 index 00000000000..5bd908cc770 --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeProcess.md @@ -0,0 +1,51 @@ +--- +title: LibErc721BridgeProcess +--- + +## LibErc721BridgeProcess + +This library provides functions for processing bridge messages on the +destination chain. + +### ERC721_B_FORBIDDEN + +```solidity +error ERC721_B_FORBIDDEN() +``` + +### ERC721_B_SIGNAL_NOT_RECEIVED + +```solidity +error ERC721_B_SIGNAL_NOT_RECEIVED() +``` + +### ERC721_B_STATUS_MISMATCH + +```solidity +error ERC721_B_STATUS_MISMATCH() +``` + +### ERC721_B_WRONG_CHAIN_ID + +```solidity +error ERC721_B_WRONG_CHAIN_ID() +``` + +### processMessage + +```solidity +function processMessage(struct LibErc721BridgeData.State state, contract AddressResolver resolver, struct IErc721Bridge.Message message, bytes proof) internal +``` + +Process the bridge message on the destination chain. It can be called by +any address, including `message.owner`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| state | struct LibErc721BridgeData.State | The bridge state. | +| resolver | contract AddressResolver | The address resolver. | +| message | struct IErc721Bridge.Message | The message to process. | +| proof | bytes | The msgHash proof from the source chain. | + diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeSend.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeSend.md new file mode 100644 index 00000000000..7942743456f --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeSend.md @@ -0,0 +1,120 @@ +--- +title: LibErc721BridgeSend +--- + +## LibErc721BridgeSend + +Entry point for starting a bridge transaction. + +### B_INCORRECT_VALUE + +```solidity +error B_INCORRECT_VALUE() +``` + +### ERC721_B_OWNER_IS_NULL + +```solidity +error ERC721_B_OWNER_IS_NULL() +``` + +### ERC721_B_WRONG_CHAIN_ID + +```solidity +error ERC721_B_WRONG_CHAIN_ID() +``` + +### ERC721_B_WRONG_TO_ADDRESS + +```solidity +error ERC721_B_WRONG_TO_ADDRESS() +``` + +### sendMessageErc721 + +```solidity +function sendMessageErc721(struct LibErc721BridgeData.State state, contract AddressResolver resolver, struct IErc721Bridge.Message message) internal returns (bytes32 msgHash) +``` + +Send a message to the Bridge with the details of the request. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| state | struct LibErc721BridgeData.State | The current state of the Bridge | +| resolver | contract AddressResolver | The address resolver | +| message | struct IErc721Bridge.Message | Specifies the `depositValue`, `callValue`, and `processingFee`. These must sum to `msg.value`. It also specifies the `destChainId` which must have a `bridge` address set on the AddressResolver and differ from the current chain ID. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| msgHash | bytes32 | The hash of the sent message. This is picked up by an off-chain relayer which indicates a bridge message has been sent and is ready to be processed on the destination chain. | + +### isDestChainEnabled + +```solidity +function isDestChainEnabled(contract AddressResolver resolver, uint256 chainId) internal view returns (bool enabled, address destBridge) +``` + +Check if the destination chain is enabled. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| resolver | contract AddressResolver | The address resolver | +| chainId | uint256 | The destination chain id | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| enabled | bool | True if the destination chain is enabled | +| destBridge | address | The bridge of the destination chain | + +### isMessageSentErc721 + +```solidity +function isMessageSentErc721(contract AddressResolver resolver, bytes32 msgHash) internal view returns (bool) +``` + +Check if the message was sent. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| resolver | contract AddressResolver | The address resolver | +| msgHash | bytes32 | The hash of the sent message | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if the message was sent | + +### isMessageReceivedErc721 + +```solidity +function isMessageReceivedErc721(contract AddressResolver resolver, bytes32 msgHash, uint256 srcChainId, bytes proof) internal view returns (bool) +``` + +Check if the message was received. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| resolver | contract AddressResolver | The address resolver | +| msgHash | bytes32 | The hash of the received message | +| srcChainId | uint256 | The id of the source chain | +| proof | bytes | The proof of message receipt | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if the message was received | + diff --git a/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeStatus.md b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeStatus.md new file mode 100644 index 00000000000..5e737888284 --- /dev/null +++ b/packages/website/pages/docs/reference/contract-documentation/nft_bridge/erc721/libs/LibErc721BridgeStatus.md @@ -0,0 +1,116 @@ +--- +title: LibErc721BridgeStatus +--- + +## LibErc721BridgeStatus + +This library provides functions to get and update the status of bridge +messages. + +### MessageStatus + +```solidity +enum MessageStatus { + NEW, + RETRIABLE, + DONE, + FAILED +} +``` + +### MessageStatusChangedErc721 + +```solidity +event MessageStatusChangedErc721(bytes32 msgHash, enum LibErc721BridgeStatus.MessageStatus status, address transactor) +``` + +### B_MSG_HASH_NULL + +```solidity +error B_MSG_HASH_NULL() +``` + +### B_WRONG_CHAIN_ID + +```solidity +error B_WRONG_CHAIN_ID() +``` + +### updateMessageStatusErc721 + +```solidity +function updateMessageStatusErc721(bytes32 msgHash, enum LibErc721BridgeStatus.MessageStatus status) internal +``` + +Updates the status of a bridge message. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| msgHash | bytes32 | The hash of the message. | +| status | enum LibErc721BridgeStatus.MessageStatus | The new status of the message. | + +### getMessageStatusErc721 + +```solidity +function getMessageStatusErc721(bytes32 msgHash) internal view returns (enum LibErc721BridgeStatus.MessageStatus) +``` + +Gets the status of a bridge message. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| msgHash | bytes32 | The hash of the message. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | enum LibErc721BridgeStatus.MessageStatus | The status of the message. | + +### isMessageFailedErc721 + +```solidity +function isMessageFailedErc721(contract AddressResolver resolver, bytes32 msgHash, uint256 destChainId, bytes proof) internal view returns (bool) +``` + +Checks if a bridge message has failed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| resolver | contract AddressResolver | The address resolver. | +| msgHash | bytes32 | The hash of the message. | +| destChainId | uint256 | The ID of the destination chain. | +| proof | bytes | The proof of the status of the message. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if the message has failed, false otherwise. | + +### getMessageStatusSlot + +```solidity +function getMessageStatusSlot(bytes32 msgHash) internal pure returns (bytes32) +``` + +Gets the storage slot for a bridge message status. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| msgHash | bytes32 | The hash of the message. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | The storage slot for the message status. | +