# Upgrade guide

This is an upgrade guide for users of `@cennznet/api.js` from `1.5.x` to `2.1.x` versions. It does not attempt to detail each version the [CHANGELOG](https://github.com/cennznet/api.js/blob/master/packages/api/CHANGELOG.md) has all the changes between versions), but tries to explain the rationale behind major changes and how users of the API should handle this.

## API.js Version Mapping

### Version `1.5.3 or lower`

`yarn add @cennznet/api`

- Node version `10`
- CENNZnet Image [cennznet/cennznet:2.0.0](https://hub.docker.com/layers/cennznet/cennznet/2.0.0/images/sha256-a3719cd7b0dc7d3c4553ca1c07ffdde084f910dde1a8cc25c65fae45c8495229?context=explore) (Mainnet as of 15th March)
- Dependent on the following `@polkadot` packages

    "@polkadot/api|types|metadata": "3.7.1",
    "@polkadot/util": "^4.2.1",
    "@polkadot/util-crypto": "^4.2.1",

### Version `2.1.0 or newer`
`yarn add @cennznet/api@2.1.0-rc.1`

- Node version `14`
- CENNZnet Image [cennznet/cennznet:2.1.0-rc4](https://hub.docker.com/layers/cennznet/cennznet/2.1.0-rc4/images/sha256-121f1a99f0fbe4d2ee9648f9e02903e17d86d5651a4e9af8b51834ac4fb9dc5e?context=explore)
- Dependent on the following `@polkadot` packages

    "@polkadot/api|types|rpc-provider": "7.7.1",
    "@polkadot/util": "^8.3.3",
    "@polkadot/util-crypto": "^8.3.3",

## Breaking Changes

### Polkadot Packages

* With the support for v14 Metadata parsing, the `documentation` fields on metadata was renamed to `docs` for consistency, aligning with the SCALE type generators.

* The `@polkadot/metadata` package has been removed, adjust imports to ``@polkadot/types`

    // OLD
    import { Metadata } from '@polkadot/metadata';
    // NEW
    import { Metadata } from '@polkadot/types/metadata';

* The `@polkadot/api-derive` types have been moved to a new location

    // OLD
    import { HeaderExtended } from '@polkadot/api-derive'; 
    // NEW
    import type { HeaderExtended } from '@polkadot/api-derive/types';

### NFT Module
1. Deprecate the `mintUnique` method, use `mintSeries` instead
2. Use new NFT Metadata Standards as described [here](https://wiki.cennz.net/#/Dapp-development/Guides/NFT-metadata-standard)
3. Change NFT data model to more closely resemble the ERC721 structure for future cross-chain compatibility.

    'Collections' are a grouping of series
    'Series' are equivalent to ERC721 home contracts
    'Serial numbers' are equivalent to ERC721 token address

4. Removes the concept of SFT/copies/unique enforced by the module, all tokens are NFTs by default. It is much simpler to leave to the token metadata to denote/manage copies.

    // OLD
    const attributes = [
        {'Text': 'Hello World'},
      ];
    const collectionId = 1; // created using api.tx.nft.createCollection
    const owner = '0x...';
    const metadataPath = null;
    const royaltiesSchedule = null;
    await api.tx.nft.mintUnique(collectionId, owner, attributes, metadataPath, royaltiesSchedule)
    .signAndSend(collectionOwner, async ({ status, events }) => {
      if (status.isInBlock) {
    events.forEach(({ event: {data, method }}) => {
      if (method == 'CreateToken') {
        tokenId = data[1];
        console.log(`got token: ${tokenId}`);
      }
    });

    // NEW
    const quantity = 1;
    const metadataPath = {"Https": "example.com/nft/metadata" };
    const collectionId = 1; // created using api.tx.nft.createCollection
    const owner = '0x...';
    const royaltiesSchedule = null;
    await api.tx.nft.mintSeries(collectionId, quantity, owner, metadataPath, royaltiesSchedule)
    .signAndSend(collectionOwner, async ({ status, events }) => {
      if (status.isInBlock) {
        events.forEach(({ event: {data, method }}) => {
          if (method == 'CreateToken') {
            tokenId = data[1];
            console.log(`got token: ${tokenId}`);
          }
    });

5. Metadata Reference Schemes
- `MetadataBaseUri` renamed to `MetadataScheme`
- Users can choose to store token metadata using 1 of 2 reference schemes, either:
1) https. token URIs assembled like `https://api.example.com/metadata/<serialNumber>.json`
2) IPFS directory. token URIs assembled like: `ipfs://<directoryCID/<serialNumber>.json`
[more details](https://github.com/cennznet/cennznet/issues/442#issuecomment-992086784)

6. `SeriesAttributes` only exist for NFT created in runtime version `< 50`
7. To get series metadata URI, use following derived query. Internally derive query uses api.query.nft.seriesMetadataURI (for older runtime version 45 ) and for new ones (api.query.nft.seriesMetadataScheme)

    const collectionId = 192;
    const seriesId = 0;
    const uri = await api.derive.nft.seriesMetadataUri(collectionId, seriesId);

9. Introduced new listing derived query which gives you list of all tokens for all the listing given a collection.

    const collectionId = '16';
    const listedTokenInfo = await api.derive.nft.openCollectionListingsV2('16'); 
    /*
     [{
        listingId: 12, 
        tokens: [
            {owner: '0x..', tokenId: [16,0,1]},
            {owner: '0x..', tokenId: [16,0,2]}
        ]
    }];
    */

### Staking Module
- All staking derive queries are moved to `stakingCennznet`

    api.derive.staking.* --> api.derive.stakingCennznet.*