Ocean.sol

Github link: https://github.com/Shell-Protocol/Shell-Protocol/blob/main/src/ocean/Ocean.sol

WRAPPED_ETHER_ID()

/// @notice this is the oceanId used for shETH
/// @dev hexadecimal(ascii("shETH"))
uint256 public immutable WRAPPED_ETHER_ID;

This function is automatically created because WRAPPED_ETHER_ID variable is declared as public.

It should...

1. Return the Ocean ID for Ether (Wrapping Ether into Ocean would result in shETH, so it would be a shETH ID actually).

unwrapFeeDivisor()

/// @notice Used to calculate the unwrap fee
/// unwrapFee = unwrapAmount / unwrapFeeDivisor
/// Because this uses integer division, the fee is always rounded down
/// If unwrapAmount < unwrapFeeDivisor, unwrapFee == 0
uint256 public unwrapFeeDivisor;

This function is automatically created because unwrapFeeDivisor variable is declared as public. A fee is charged by the Ocean on each unwrap.

It should...

1. Return the correct unwrap fee divisor.

doInteraction()

/**
* @notice Execute interactions `interaction`
* @notice Does not need ids because a single interaction does not require
*  the accounting system
* @dev MUST HAVE nonReentrant modifier.
* @dev call to _doInteraction() binds msg.sender to userAddress
* @param interaction Executed to produce a set of balance updates
*/
function doInteraction(
    Interaction calldata interaction
) external override nonReentrant returns (
    uint256 burnId,
    uint256 burnAmount,
    uint256 mintId,
    uint256 mintAmount
);

Parameter Name	Type	Description
interaction	Interaction struct	one of nine different interactions types encoded via the Interaction struct

Interaction Struct Params:

Parameter Name	Type	Description
interactionTypeAndAddress	bytes32	a bytes32 array that combines both the interaction type and the address of the external contract called during this interaction
inputToken	uint256	input token Ocean ID
outputToken	uint256	output token Ocean ID
specifiedAmount	uint256	amount of the specified token
metadata	bytes32	bytes32 array of arbitrary data, during 721/1155 and wraps and unwraps we use this filed to pass token ID

This function executes a single interaction.

It should...

1. Execute a single forwarded interaction.

doMultipleInteractions()

/**
* @notice Execute interactions `interactions` with tokens `ids`
* @notice ids must include all tokens invoked during the transaction
* @notice ids are used for memory allocation in the intra-transaction
*  accounting system.
* @dev MUST HAVE nonReentrant modifier.
* @dev call to _doMultipleInteractions() binds msg.sender to userAddress
* @param interactions Executed to produce a set of balance updates
* @param ids Ocean IDs of the tokens invoked by the interactions.
*/
function doMultipleInteractions(
    Interaction[] calldata interactions,
    uint256[] calldata ids
) external payable override nonReentrant returns (
    uint256[] memory burnIds,
    uint256[] memory burnAmounts,
    uint256[] memory mintIds,
    uint256[] memory mintAmounts
);

Parameter Name	Type	Description
interactions	Interaction struct[]	an array of interactions which can be one of nine different interactions types encoded via the Interaction struct
ids	uint256[]	an array of tokens Ocean IDs used by the interactions forwarded by the interactions param

Interaction Struct Params:

Parameter Name	Type	Description
interactionTypeAndAddress	bytes32	a bytes32 array that combines both the interaction type and the address of the external contract called during this interaction
inputToken	uint256	input token Ocean ID
outputToken	uint256	output token Ocean ID
specifiedAmount	uint256	amount of the specified token
metadata	bytes32	bytes32 array of arbitrary data, during 721/1155 and wraps and unwraps we use this filed to pass token ID

This function executes multiple interactions in order they were stacked in the array of interactions. Use this function to compose different interactions, i.e. Ocean native primitives.

It should...

1. Execute a a list of forwarded interactions.

forwardedDoInteraction()

/**
* @notice Execute interactions `interactions` on behalf of `userAddress`
* @notice Does not need ids because a single interaction does not require
*  the overhead of the intra-transaction accounting system
* @dev MUST HAVE nonReentrant modifier.
* @dev MUST HAVE onlyApprovedForwarder modifer.
* @dev call to _doMultipleInteractions() forwards the userAddress
* @param interaction Executed to produce a set of balance updates
* @param userAddress interactions are executed on behalf of this address
*/
function forwardedDoInteraction(
    Interaction calldata interaction,
    address userAddress
)
external override nonReentrant onlyApprovedForwarder(userAddress) returns (
    uint256 burnId,
    uint256 burnAmount,
    uint256 mintId,
    uint256 mintAmount
);

Parameter Name	Type	Description
interaction	Interaction struct	one of nine different interactions types encoded via the Interaction struct
userAddress	address	address on which behalf to execute interactions

Interaction Struct Params:

Parameter Name	Type	Description
interactionTypeAndAddress	bytes32	a bytes32 array that combines both the interaction type and the address of the external contract called during this interaction
inputToken	uint256	input token Ocean ID
outputToken	uint256	output token Ocean ID
specifiedAmount	uint256	amount of the specified token
metadata	bytes32	bytes32 array of arbitrary data, during 721/1155 and wraps and unwraps we use this filed to pass token ID

This function executes a single interaction on behalf the address that was forwarded as userAddress param.

It should...

1. Revert if address forwarded as userAddress param hasn't approved message sender to pass interactions on its behalf via isApprovedForAll ERC1155 method.

2. Execute a single forwarded interaction.

forwardedDoMultipleInteractions()

/**
* @notice Execute interactions `interactions` with tokens `ids` on behalf of `userAddress`
* @notice ids must include all tokens invoked during the transaction
* @notice ids are used for memory allocation in the intra-transaction
*  accounting system.
* @dev MUST HAVE nonReentrant modifier.
* @dev MUST HAVE onlyApprovedForwarder modifer.
* @dev call to _doMultipleInteractions() forwards the userAddress
* @param interactions Executed to produce a set of balance updates
* @param ids Ocean IDs of the tokens invoked by the interactions.
* @param userAddress interactions are executed on behalf of this address
*/
function forwardedDoMultipleInteractions(
    Interaction[] calldata interactions,
    uint256[] calldata ids,
    address userAddress
)
external payable override nonReentrant onlyApprovedForwarder(userAddress) returns (
    uint256[] memory burnIds,
    uint256[] memory burnAmounts,
    uint256[] memory mintIds,
    uint256[] memory mintAmounts
);

Parameter Name	Type	Description
interactions	Interaction struct[]	an array of interactions which can be one of nine different interactions types encoded via the Interaction struct
ids	unit256[]	an array of interaction IDs forwarded by the first param Interaction struct[]
userAddress	address	address on which behalf to execute interactions

Interaction Struct Params:

Parameter Name	Type	Description
interactionTypeAndAddress	bytes32	a bytes32 array that combines both the interaction type and the address of the external contract called during this interaction
inputToken	uint256	input token Ocean ID
outputToken	uint256	output token Ocean ID
specifiedAmount	uint256	amount of the specified token
metadata	bytes32	bytes32 array of arbitrary data, during 721/1155 and wraps and unwraps we use this filed to pass token ID

This function executes multiple interactions in order they were stacked in the array of interactions on behalf the address that was forwarded as the userAddress param. Use this function to compose different interactions, i.e. Ocean native primitives.

It should...

1. Revert if address forwarded as userAddress param hasn't approved message sender to pass interactions on its behalf via isApprovedForAll ERC1155 method.

2. Execute a single forwarded interaction.

registerNewTokens()

/**
* @dev Registered Tokens are tokens issued directly on the ocean's 1155 ledger.
* @dev These are tokens that cannot be wrapped or unwrapped.
* @dev We don't validate the inputs.  The happy path usage is for callers
*  to obtain authority over tokens that have their ids derived from
*  successive nonces.
*
*  registerNewTokens(0, n):
*      _calculateOceanId(caller, 0)
*      _calculateOceanId(caller, 1)
*      ...
*      _calculateOceanId(caller, n)
*
*  Since the ocean tracks the one to one relationship of:
*    token => authority
*  but not the one to many relationship of:
*    authority => tokens
*  it is nice UX to be able to re-derive the tokens on the fly from the
*  authority's address and successive (predictable) nonces are used.
*
*  However, if the caller wants to use this interface in a different way,
*  they could easily make a call like:
*  registerNewTokens($SOME_NUMBER, 1); to use $SOME_NUMBER
*  as the nonce.  A user could request to buy an in-ocean nft with a
*  specific seed value, and the external contract gains authority over
*  this id on the fly in order to sell it.
*
*  If the caller tries to reassert authority over a token they've already
*  registered, they just waste gas.  If a caller expects to create
*  new tokens over time, it should track how many tokens it has already
*  created
* @dev the guiding philosophy is to track only essential information in
*  the Ocean's state, and let users (both EOAs and contracts) track other
*  information as they see fit.
* @param currentNumberOfTokens the starting nonce
* @param numberOfAdditionalTokens the number of new tokens registered
* @return oceanIds Ocean IDs of the tokens the caller now has authority over
*/
function registerNewTokens(
   uint256 currentNumberOfTokens,
   uint256 numberOfAdditionalTokens
) external override returns (
   uint256[] memory oceanIds
);

Parameter Name	Type	Description
currentNumberOfTokens	uint256	current number of tokens as a starting nonce
numberOfAdditionalTokens	unit256	the number of new tokens to be registered

This functions should register new tokens that are issued directly on the Ocean's ERC-1155 ledger.

supportsInterface()

A standard implementation of ERC165 supportsInterface method which checks for IERC1155, IERC1155MetadataURI or IERC165 implementations. For more details see check the official EIP-165 page or OpenZeppelin Introspection page.

Other methods

Below is a list of other public and external methods accessible in the Ocean smart contract, which may not be as relevant. Most of these methods are implemented as part of the ERC-1155 specification.

uri()

This function is an implementation of the ERC-1155 uri method. For more details, check the Metadata section of the EIP-1155 page.

onERC721Received()

This function is an implementation of the onERC721Received method from the IERC721Receiver interface contract. For more details, check the interface ERC721TokenReceiver part of the specification section of the EIP-721 page.

onERC1155Received()

This function is an implementation of the onERC1155Received method from the IERC1155TokenReceiver interface contract. For more details, check the ERC-1155 Token Receiver section of the EIP-1155 page.

onERC1155BatchReceived()

This function is an implementation of the onERC1155BatchReceived method from the IERC1155TokenReceiver interface contract. For more details check the ERC-1155 Token Receiver section of the EIP-1155 page.

balanceOf()

This function is an implementation of the balanceOf method from the IERC1155 interface contract. For more details, check the specification section of the EIP-1155 page.

balanceOfBatch()

This function is an implementation of the balanceOfBatch method from the IERC1155 interface contract. For more details, check the specification and Batch Balance sections of the EIP-1155 page.

setApprovalForAll()

This function is an implementation of the setApprovalForAll method from the IERC1155 interface contract. For more details, check the specification and Approval sections of the EIP-1155 page.

isApprovedForAll()

This function is an implementation of the isApprovedForAll method from the IERC1155 interface contract. For more details, check the specification and Approval sections of the EIP-1155 page.

safeTransferFrom()

This function is an implementation of the safeTransferFrom method from the IERC1155 interface contract. For more details, check the specification and Safe Transfer Rules sections of the EIP-1155 page.

safeBatchTransferFrom()

This function is an implementation of the safeBatchTransferFrom method from the IERC1155 interface contract. For more details, check the specification and Batch Transfers sections of the EIP-1155 page.