Native Extension

Native Extension code - Native Extension address

Factory Approach

The Native Extension, implementing the LazyInitCapableElement contract, is factory-capable contract, meaning that it can be cloned and initialized via the Extension Factories. Only the EthereansOS private team multi-sig has the right to add a new Extension clonable model to the Extension Factories while everyone can clone an Extension from one of the available models.

Granular Permissions

The Extension can assign one permission to an operator:

  1. Change Collection and / or Item metadata

The Create and / or mint Items permission and the Finalize permission are managed by the Native Extension host.

Only the name, symbol and uri of the Collection/ Items can be changed by the Extension; the Collection host cannot be changed.

The assigned Operator address—and no one else—can reassign the permission to a new Operator address.

There can only be one Operator address per permission:

 function setMetadataHost(address newValue) external returns(address oldValue) {
     require(msg.sender == metadataHost, "unauthorized");
     oldValue = metadataHost;
     metadataHost = newValue;
}

To reiterate, permissions aside from the two outlined above can’t be assigned and once a Collection is linked to a Native, it can’t be linked to another extension

Items Finalization

Using the Native Extension, the Extension host address (the one that has also minting permission) can decide to let an Item no more mintable. An Item of this kind is called a finalized Item.

Each Item controlled by a Native Extension can have:

  • finalized as false

  • finalized as true

An Item not finalized (finalized false) can be minted by the host Extension address as a normal Item. An Item finalized (finalized as true) cannot be minted anymore not even from the Extension host.

The finalized parameter is managed by the isFinalized mapping in the Native Extension contract.

Finalizing operations

You can finalize an Item in 4 different moments:

  1. When initializing the Extension contract creating also one or more Items.

  2. When creating the Item using the mintItem(CreateItem[] calldata items, bool[] memory finalized) function.

  3. When minting the Item using the mintItem(CreateItem[] calldata items, bool[] memory finalized) function.

  4. When using the finalize(uint256[] calldata itemIds) function.

An Item finalized can not return to be unfinalized (finalized false), it is irreversible.

Decimals

An itemId created via an Extension has 18 decimals on both the Main interface (the ERC1155 interface) and on its Interoperable Interface (its ERC20 interface).

Native Extension deploy and initialization

When you deploy a Native Extension, you also automatically create the Items collection.

The Native Extension must be cloned using the deploy method of the Extension Factory:

function deploy(bytes calldata deployData) external payable override(Factory, IFactory) returns(address deployedAddress, bytes memory deployedLazyInitResponse)

To correctly initialize the Native Extension, you have to pass the deployData in this way:

//finalized, i.e. items to be finalized
var data = web3.eth.abi.encodeParameters(["bool[]"], [[],[]]);
//Collection data to create the Items Collection within the Extension
data = abi.encode(
  [
    "bytes32",
    "tuple(address,string,string,string)",
    "tuple(tuple(address,string,string,string),bytes32,uint256,address[],uint256[])[]",
    "bytes",
  ],
  [utilities.voidBytes32, header, item, data]
);
//Extension Operator, i.e Metadata operator
data = web3.eth.abi.encodeParameters(["address", "bytes"], [0x.., data]);
//Extension Operator, ie. Mint and finalize opertor
data = web3.eth.abi.encodeParameters(["address", "bytes"], [0x.., data]);
//Factory model index
data = web3.eth.abi.encodeParameters(["uint256", "bytes"], [1, data]);
//Clone the Extension using the Extension Factory
var transaction = await itemProjectionFactory.methods.deploy(data).send({from : accounts[1]});

Actually, using the current existing Extension models, you can’t do this because the host of a Collection can’t be changed after contract initialization.

So you have to create the Collection within the Extension

Functions

Change Mint and Finalize Operator address

function setHost(address newValue) external override authorizedOnly returns(address oldValue)
  • Function type: write

  • Callable by:

    • Mint and Finalize Operator address

This function is used to change the Mint and Finalize Operator address and can only be called by the current Mint and Finalize Operator address.

Change Metadata Operator address

function setMetadataHost(address newValue) external returns(address oldValue)
  • Function type: write

  • Callable by:

    • Metadata Operator address

This function is used to change the Metadata Operator address and can only be called by the current Metadata Operator address.

Create/Mint Items

function mintItems(CreateItem[] memory items) authorizedOnly virtual override public returns(uint256[] memory itemIds)
  • Function type: write.

  • Callable by:

    • Mint and Finalize Operator address

This function can be used to create a new Item id or to mint a new amount of an existing Item id inside an already existing Collection.

In the first case, the id parameter of the CreateItem must be passed as 0. In the second case, it must be passed as the existing item id to mint.

Items created/minted using this function have finalized as false and so are mintable.

function mintItems(CreateItem[] calldata items, bool[] memory finalized) authorizedOnly public returns(uint256[] memory itemIds)
  • Function type: write.

  • Callable by:

    • Mint and Finalize Operator address

In the first case, the id parameter of the CreateItem must be passed as 0. In the second case, it must be passed as the existing item id to mint.

The logic of the function is the same as the previous one. The function takes as input an array of CreateItem struct and an array of finalized (bool[]).

If finalized is passed as false or it's not specified, the created/minted Items are mintable.

If finalized is passed as true, the created/minted items are finalized and no more mintable and the finalization is irreversible.

Finalize Items

function finalize(uint256[] calldata itemIds) external authorizedOnly
  • Function type: write.

  • Callable by:

    • Mint and Finalize Operator address

This function can be used by the Mint and Finalize Operator to finalize existing Items. The function takes as input an array of Item ids and it puts all the Item passed as finalized (so finalize as true). The Items finalized are no more mintable and the finalization is irreversible.

Change Collection and Items Metadata

Change Collection Metadata

function setHeader(Header calldata value) authorizedOnly external returns(Header memory oldValue);
  • Function type: write.

  • Callable by:

    • Operator address with the Metadata permission

This function is used to change the Header, and thereby the metadata, of the Collection linked to the Extension.

The input function is the new Header struct (address host, string name, string symbol, string uri).

The host address cannot be changed.

The function output represents the old Collection Header.

Change Items Metadata

function setItemsMetadata(uint256[] calldata itemIds, Header[] calldata values) authorizedOnly override external returns(Header[] memory oldValues);
  • Function type: write

  • Callable by:

    • Operator address with the Metadata permission

This function is used to change the Collection’s Items Metadata. As input, it takes an array of itemIds, and a corresponding new Header struct that contains the new Metadata.

Keep in mind that an Item has no host, so even if a host address is passed, the host will automatically be set as address(0).

The function’s output represents the old Items’ Header.

Last updated