v1.4.1: Rental NFT - Helpers

This release aims to improve the Rental NFT developer experience (DX) with some useful helpers, and provides a bunch of minor fixes:
- numberToBalance function is now synchrone.
- Rent formatters added
- formatRentContractFee is deprecated and replaced by validateTransformContractFee

Breaking changes (1)

• formatRentContractFee is deprecated and replaced by validateTransformContractFee

Added Formatters(5) :

Find the code here (./src/rent/utils.ts).

• formatDuration - Returns an object representing a duration in either fixed or subscription format.
• formatAcceptanceType - Returns an object representing an acceptance type in either auto or manual format.
• formatRentFee - Returns an object representing a rent fee in either tokens or NFT format.
• formatCancellationFee - Returns an object representing a cancellation fee in either fixed, flexible or NFT format.
• validateTransformContractFee - Validates the fee type and format it accordingly. Numbers are formatted into BN.

To learn more about how to use those formatters, check our documentation.

Deleted functions (1)

• formatRentContractFee

v1.4.0: Rental NFT / English auction

This release aims to close fully Ternoa Phase 3 with two new pallets and a Marketplace pallet improvement:
- Rent Pallet ✍️ - #84 @Victor-Salomon
- Auction Pallet 👩‍⚖️ - #83 @ipapandinas
- Marketplace can now whitelist or ban collections @Victor-Salomon

Note: again, several breaking changes have been implemented in this version ⚠️
It is strongly recommend to update your application according to both v1.3.1 and the following changes.

Breaking changes (1)

• setMarketplaceConfiguration now require a new parameter : No operation (Noop) /Remove/Set to whitelist or ban some specific collectionIds from listing. Event from submitTxBlocking now also returns an array of the whitlisted collectionId.

Added (3)

1- Rent Pallet ✍️

This pallet is a complex module to create and handle rental contracts of NFT. The related TIP is TIP-400.

rent/constants

• getAccountSizeLimit - The maximum number of accounts that can be stored inside the account list of acceptance.
• getActionsInBlockLimit - Maximum number of related automatic rent actions in block.
• getMaximumContractAvailabilityLimit - Maximum number of blocks during which a rent contract is available.
• getMaximumContractDurationLimit - Maximum number of blocks that a contract can last for.
• getSimultaneousContractLimit - Maximum number of simultaneous rent contract.

rent/extrinsics

• createContract - Creates a rental contract on the chain for an NFT.
• cancelContract - Cancels a contract that is not running.
• revokeContract - Revokes a running contract.
• rent - Rents an nft.
• makeRentOffer - Makes an offer for an available contract.
• retractRentOffer - Retracts a rent offer for manual acceptance contract.
• acceptRentOffer - Accepts a rent offer for manual acceptance contract.
• changeSubscriptionTerms - Changes the subscription terms for subscription contracts.
• acceptSubscriptionTerms - Accepts the subscription terms for subscription contracts.

rent/storage

• getRentalContractData - Provides the data related to a rent contract.
• getRentalOffers - Provides the data related to rent contracts offers.
• getRentingQueues - Provides the deadlines related to contracts in queues for available contracts, running fixed contract and running subscribed contract.

rent/utils

• formatRentFee - Checks the type fee and format it accordingly. Numbers are formatted into BN.

2- Auction Pallet 👩‍⚖️

This pallet is a complex module to create and handle rental contracts of NFT. The related TIP is TIP-300.

auction/constants

• getAuctionEndingPeriod - Period (in blocks) before the end of the auction during which an auction can be extended if new bids are added.
• getAuctionGracePeriod - Period (in blocks) to extend an auction by if a new bid is received during the ending period.
• getBidderListLengthLimit - Total amount of accounts that can be in the bidder list for an auction.
• getMaxAuctionDelay - Maximum amount of blocks between the current one and the start block of an auction.
• getMinAuctionDuration - Minimum amount of blocks permitted for an auction's length.
• getMaxAuctionDuration - Maximum amount of blocks permitted for an auction's length.
• getParallelAuctionLimit - Maximum amount of auctions that can be active at the same time.

auction/extrinsics

• createAuction - Creates an auction for an NFT.
• cancelAuction - Cancels an auction for an NFT.
• endAuction - Ends an auction for an NFT.
• addBid - The bidder adds a new bid offer.
• removeBid - The bidder removes his bid offer.
• buyItNow - The NFT can be directly buy if a buyItPrice was defined and the auction has not started yet.
• claim - Bidders that did not win the auction have to claim back their bids balance after an auction ends.

auction/storage

• getAuctionData - Provides the data related to an auction.
• getAuctionDeadline - Provides the auction ending block.
• getClaimableBidBalance - Bids balance claimable after an auction ends.

3- Marketplace whitelist of NFT collections 🛩:

• setMarketplaceConfiguration require a new parameter to whitelist or ban some specific collectionId.
• MarketplaceConfigSetEvent - now returns the collectionId of whitelisted or banned collections.

Deleted functions (3)

• dateToBlockNumber
• blockNumberToMsDuration
• msDurationToBlockNumber

v1.4.0-rc0 : Rent & Auction pallets

This alpha release aims to close fully Ternoa Phase 3.

• 2 New Pallets + Marketplace Pallet improvement
  • Rent Pallet ✍️ - #84
  • Auction Pallet 👩‍⚖️ - #83
  • Marketplace can now whitelist or ban collections

Note: again, several breaking changes have been implemented in this version ⚠️
It is strongly recommend to update your application according to both v1.3.1 and the following changes.

Breaking changes (2)

• setMarketplaceConfiguration now require a new parameter : No operation (Noop) /Remove/Set to whitelist or ban some specific collectionIds from listing. Event from submitTxBlocking now also returns an array of the whitlisted collectionId.

• listedForSale is deprecated and replaced by isListed in the NftState (issue #80)

   export type NftState = {
     ...
     isListed: boolean // 👈 The new version of the previous 'listedForSale' field
   }

  Impact: The storage getter getNftData will return the new isListed field in the NFT state data.

Added (3)

1- Rent Pallet ✍️

This pallet is a complex module to create and handle rental contracts of NFT. The related TIP is TIP-400.

rent/constants

• getAccountSizeLimit - The maximum number of accounts that can be stored inside the account list of acceptance.
• getActionsInBlockLimit - Maximum number of related automatic rent actions in block.
• getMaximumContractAvailabilityLimit - Maximum number of blocks during which a rent contract is available.
• getMaximumContractDurationLimit - Maximum number of blocks that a contract can last for.
• getSimultaneousContractLimit - Maximum number of simultaneous rent contract.

rent/extrinsics

• createContract - Creates a rental contract on the chain for an NFT.
• cancelContract - Cancels a contract that is not running.
• revokeContract - Revokes a running contract.
• rent - Rents an nft.
• makeRentOffer - Makes an offer for an available contract.
• retractRentOffer - Retracts a rent offer for manual acceptance contract.
• acceptRentOffer - Accepts a rent offer for manual acceptance contract.
• changeSubscriptionTerms - Changes the subscription terms for subscription contracts.
• acceptSubscriptionTerms - Accepts the subscription terms for subscription contracts.

rent/storage

• getRentalContractData - Provides the data related to a rent contract.
• getRentalOffers - Provides the data related to rent contracts offers.
• getRentingQueues - Provides the deadlines related to contracts in queues for available contracts, running fixed contract and running subscribed contract.

rent/utils

• formatRentFee - Checks the type fee and format it accordingly. Numbers are formatted into BN.

2- Auction Pallet 👩‍⚖️

This pallet is a complex module to create and handle rental contracts of NFT. The related TIP is TIP-300.

auction/constants

• getAuctionEndingPeriod - Period (in blocks) before the end of the auction during which an auction can be extended if new bids are added.
• getAuctionGracePeriod - Period (in blocks) to extend an auction by if a new bid is received during the ending period.
• getBidderListLengthLimit - Total amount of accounts that can be in the bidder list for an auction.
• getMaxAuctionDelay - Maximum amount of blocks between the current one and the start block of an auction.
• getMinAuctionDuration - Minimum amount of blocks permitted for an auction's length.
• getMaxAuctionDuration - Maximum amount of blocks permitted for an auction's length.
• getParallelAuctionLimit - Maximum amount of auctions that can be active at the same time.

auction/extrinsics

• createAuction - Creates an auction for an NFT.
• cancelAuction - Cancels an auction for an NFT.
• endAuction - Ends an auction for an NFT.
• addBid - The bidder adds a new bid offer.
• removeBid - The bidder removes his bid offer.
• buyItNow - The NFT can be directly buy if a buyItPrice was defined and the auction has not started yet.
• claim - Bidders that did not win the auction have to claim back their bids balance after an auction ends.

auction/storage

• getAuctionData - Provides the data related to an auction.
• getAuctionDeadline - Provides the auction ending block.
• getClaimableBidBalance - Bids balance claimable after an auction ends.

3- Marketplace whitelist of NFT collections 🛩:

• setMarketplaceConfiguration require a new parameter to whitelist or ban some specific collectionId.
• MarketplaceConfigSetEvent - now returns the collectionId of whitelisted or banned collections.

Deleted functions (3)

• dateToBlockNumber
• blockNumberToMsDuration
• msDurationToBlockNumber

v1.3.1

This release brings a new IPFS Client, improves Error logging & Batch operations, provides block data in submitTxBlocking and embeds several cleanings:

• errors management enhanced #110
• New forceBatch helper & batch checks #110
• useful datas added when submitting a tx #86
• better code consistency #107,
• more friendly/humanized datas #108
• packages upgrade #77
• (...)

Note: a bunch of breaking changes have been implemented in this version ⚠️
It is strongly recommend to update your application accordingly.

Breaking changes (3)

• Return block data informations in submitTxBlocking: (issue #86) :
  The function now returns an object with: blockInfo (block hash, block data) and events (the array of events that was sent before).

// BEFORE
const events = await submitTxBlocking(tx, waitUntil, keyring)

// NOW
const { events } = await submitTxBlocking(tx, waitUntil, keyring)

• isTransactionSuccess function deprecated and replaced by checkTransactionSuccess.
• Types/Interfaces renaming in src/nft/types: (issue #107)
  • INftData renamed as NftData
  • ICollectionData renamed as CollectionData

Added (3)

New TernoaIPFS client 🌐

TernoaIPFS client makes file & metadata storing on IPFS easier. You can upload NFTs, Collections & Marketplaces directly based compliant with the Ternoa TIP standards.

New forceBatch helper & batch checks 🔧

SDK now handle forceBatch and dedicated batch checks helpers 💥 (issue #110)

• forceBatchTx - Create a forceBatch transaction of dispatch calls.
• forceBatchTxHex - Create a forceBatch transaction of dispatch calls in hex format.
• Related Events - ItemFailedEvent and BatchCompletedWithErrorsEvent have been added to our events helpers in order to monitor forceBatch transactions.
• checkBatch - Check if a classic batch of transactions is successful without being interrupted.
• checkForceBatch - Check if a forceBatch of transactions is completed without errors.
• checkBatchAll - Check if a batchAll of transactions is succeeded or failed.

Libraries 📚

• axios (0.27.x)
• formdata-node (4.4.x)
• form-data-encoder (1.7.x)
• stream (0.0.x)
• (+ devDependancies)

Fixes (4)

• Packages upgrade: @polkadot/api version 9.6.1 #77
• getMarketplaceData() now return only humanized/friendly values instead of hexadecimal.
• ExtrinsicFailedEvent, BatchInterruptedEvent error detail fixed. Now explicit error message is catched when those events are thrown. #110 @ogous 🏆
• findEventOrThrow method from the BlockchainEvents Class now return the corresponding error detail alongside of the EXTRINSIC_FAILED error.

v1.3.0: Assets

This release is the first release for the Assets pallet integration.
Note: There is no change from v1.3.0-rc0.

Breaking changes

• Export renaming in src/index.ts:
  • accountModule renamed Account: export * as Account from “./account”
  • balanceModule renamed Balance: export * as Balance from “./balance”

Assets pallet 🪙

This pallet is a simple module to deal with fungible assets that are meant for use within a dApp.
The related TIP is TIP-600, only the transfer extrinsic is implemented for the moment.

assets/extrinsics

• assetTransferTx - Creates an unsigned unsubmitted Assets-Transfer Transaction Hash.
• assetTransfer - Transfers some balance to another account.

assets/storage

• getAccountAssetData - The holdings of a specific account for a specific asset.
• getAssetBalance - Get the balance of an account for a specific asset.

assets/types

• AccountAssetDataType

Added

• IPFS upload helpers #52
• Lib form-data (4.0.0) #105 (@nicolapertosa 🏆)
• README improved #109

Fixes

• Added missing exports of functions/folders #106

v1.2.0: Marketplaces

This is the stable release for Marketplace functions.
Note: There is no change from v1.2.0-rc0.

Breaking changes

• formatRoyalty function replaced by formatPermill.
• hex2a function deleted and replaced by polkadot native hexToString.
• File tree improvement : misc folders replaced by utils. Types file contains now the Interfaces and Type. Enum file contains all enum.
• Update blockchain events formatted to provide a more friendly datas.

Added functions

Marketplace

constants

• getMarketplaceOffchainDataLimit - The maximum offchain data length.
• getMarketplaceAccountSizeLimi t- The maximum accounts possible in the accountList.

extrinsics

• createMarketplaceTx - Creates an unsigned unsubmitted Create-Marketplace Transaction Hash.
• createMarketplace - Creates a Marketplace on the chain.
• setMarketplaceConfigurationTx - Creates an unsigned unsubmitted Set-Marketplace-Configuration Transaction Hash.
• setMarketplaceConfiguration - Set or Remove (Noop for No Operation) the marketplace parameters configuration : Commission fee, listing fee, the account list or any offchain datas.
• setMarketplaceOwnerTx - Creates an unsigned unsubmitted Set-Marketplace-Owner Transaction Hash.
• setMarketplaceOwner - Set the new marketplace owner on the chain.
• setMarketplaceKindTx - Creates an unsigned unsubmitted Set-Marketplace-Kind Transaction Hash.
• setMarketplaceKind - Set the new marketplace kind on the chain.
• listNftTx - Creates an unsigned unsubmitted List-NFT Transaction Hash.
• listNft - Lists an NFT on a marketplace.
• unlistNftTx - _ Creates an unsigned unsubmitted Unlist-NFT Transaction Hash._
• unlistNft - Unlists an NFT from a marketplace.
• buyNftTx - Creates an unsigned unsubmitted Buy-NFT Transaction Hash.
• buyNft - _ Buys an NFT on a marketplace._
• setMarketplaceMintFeeTx - Creates an unsigned unsubmitted Set-Marketplace-Mint-Fee Transaction Hash.
• setMarketplaceMintFee - Set the new marketplace minting fee on the chain.

storage

• getMarketplaceMintFee - Fee to mint a Marketplace. (extra fee on top of the tx fees).
• getNextMarketplaceId - Get the next Marketplace Id available.
• getMarketplaceData - Provides the data related to a marketplace.
• getNftForSale - Provides the data related to an NFT listed for sale.

utils

• formatMarketplaceFee - Checks the type fee and format it accordingly. Numbers are formatted into BN. Percentages are formatted in Permill.

Changed functions

• formatRoyalty function replaced by formatPermill.

Deleted functions

• hex2a function. (Use hexToString)

Documentation

Exemple/Cookbook :

Marketplace functions added to the Basic-Usage exemple.

v1.1.0: Basic NFTs / Collections

This is the stable release for basic NFTs & collections functions.
Note: There is no change from v1.1.0-rc0.

Breaking changes

• In this major version an API instance must be initialize using the initializeApi function in ternoa-js/blockchain before calling some SDK functions. The default chain endpoint is: DEFAULT_CHAIN_ENDPOINT = "wss://alphanet.ternoa.com" for the Alphanet chain. It can be modified by passing a new endpoint as a parameter to the initializeApi function.

• Txns helpers return now the related chain events. An alternative function exists to retrieve the transaction hex.

• File tree is now organize based on helper types: constants/extrinsics/index/misc/storage.

Added functions

NFT

constants

• getInitialMintFee - Original mint fee.
• getCollectionSizeLimit - Maximum collection length.
• getNftOffchainDataLimit - Provides the maximum offchain data length.
• getCollectionOffchainDataLimit - Provides the maximum offchain data length.

extrinsics

NFT txns

• createNftTx - Creates an unsigned unsubmitted Create-NFT Transaction Hash.
• createNft - Creates an NFT on the chain.
• burnNftTx - Creates an unsigned unsubmitted Burn-NFT Transaction Hash.
• burnNft - Burns an NFT on the chain.
• delegateNftTx - Creates an unsigned unsubmitted Delegate-NFT Transaction Hash.
• delegateNft - Delegates an NFT on the chain.
• setRoyaltyTx - Creates an unsigned unsubmitted Set-Royalty Transaction Hash.
• setRoyalty - Sets the royalty of an NFT.
• transferNftTx - Creates an unsigned unsubmitted Transfer-NFT Transaction Hash.
• transferNft - Sends an NFT to someone.
• addNftToCollectionTx - Creates an unsigned unsubmitted Add-NFT-To-Collection Transaction Hash.
• addNftToCollection - Adds an NFT to an existing collection.

Collection txns

• createCollectionTx - Creates an unsigned unsubmitted Create-Collection Transaction Hash.
• createCollection - Creates a collection.
• limitCollectionTx - Creates an unsigned unsubmitted Limit-Collection Transaction Hash.
• limitCollection - Limits how many NFTs can be associated with this collection.
• closeCollectionTx - Creates an unsigned unsubmitted Close-Collection Transaction Hash.
• closeCollection - Closes the collection so that no new NFTs can be added.
• burnCollectionTx - Creates an unsigned unsubmitted Burn-Collection Transaction Hash.
• burnCollection - Burns an existing collection. The collections needs to be empty before it can be burned.

misc

• formatRoyalty - Checks that royalty is in range 0 to 100 and format to permill.

storage

• nftMintFee - Fee to mint an NFT (extra fee on top of the tx fees).
• getNextNftId - Get the next NFT Id available.
• getNextCollectionId - Get the next collection Id available.
• getNftData - Provides the data related to one NFT.
• getCollectionData - Provides the data related to one NFT collection.

Balance

storage

• getTotalBalance - Get the total balance of an account (free & reserve balances)
• getTransferrableBalance - Get the transferrable balance of an account.

Blockchain txns

• submitTxBlocking - Signs and submits a transaction. It blocks the execution flow until the transaction is in a block or in a finalized block.
• submitTxNonBlocking - Signs and submits a transaction in a non-blocking way. Signing is optional.

Changed functions

Balance txns

• balancesTransferTx - Creates an unsigned unsubmitted Balance-Transfert Transaction Hash.
• balancesTransfer - Transfers some liquid free balance to another account.
• balancesTransferAllTx - Creates an unsigned unsubmitted Balance-TransfertAll Transaction Hash.
• balancesTransferAll - Transfers the entire transferable balance from the caller account.
• balancesTransferKeepAliveTx - Creates an unsigned unsubmitted Balance-TransfertKeepAlive Transaction Hash.
• balancesTransferKeepAlive - Transfers some liquid free balance to another account with a check that the transfer will not kill the origin account.

Blockchain helpers

• getRawApi - Get initialized substrate Api instance.
• getTxInitialFee - Get the weight fee estimation for a transaction.
• getTxAdditionalFee - Get the fee needed by Ternoa for specific transaction services.
• getTxFees - Get the total fees for a transaction hex.
• createTx - Create a transaction.
• createTxHex - Create a transaction in hex format.
• signTxHex - Sign a transaction.
• submitTxHex - Send a signed transaction on the blockchain.
• balanceToNumber - Format balance from BN to number.
• numberToBalance - Format balance from number to BN.

Deleted functions

• fee folder deleted, helpers moved to blockchain
• getFreeBalance
• runTx

Fixes

• total removed from getBalances

v1.0

v1.0

ternoa-js SDK is the easiest way to build on top of Ternoa chain.
Releases will be punctuated by the mainnet roadmap.

Support for Ternoa current Alphanet and Mainnet version 1.0.
On future upgrades, take care of looking at the CHANGELOG.

Here are the first features of phase 1:

Functions

Account

• generateSeed - Generate a new account
• getKeyringFromSeed - Create a keyring from a seed

Balance

• getBalance - Get the free balance of an account
• checkBalanceForTransfer - Check if an account as enough funds to ensure a transfer
• transfer -Transfer some liquid free balance to another account
• transferAll -Transfer the entire transferable balance from the caller account
• transferKeepAlive -Transfer some liquid free balance to another account with a check that the transfer will not kill the origin account

Blockchain

• initializeApi - Initialize substrate api with selected or default wss endpoint
• getApi - Get initialized substrate Api instance
• isApiConnected -Check if the Api instance existed and if it is connected
• getApiEndpoint -Provides the wss api endpoint
• safeDisconnect - Disconnect safely from the underlying provider, halting all network traffic
• query - Generic function to make a chain query
• consts - Generic function to get a chain constant
• isTransactionSuccess - Check if a transaction result is successful
• checkTxAvailable - Check if the pallet module and the subsequent extrinsic method exist in the Api instance
• createTxHex - Create a transaction in hex format
• signTx - Sign a transaction
• submitTx - Send a signed transaction on the blockchain
• runTx - Create, sign and submit a transaction on blockchain
• batchTx - Create a batch transaction of dispatch calls
• batchTxHex - Create a batch transaction of dispatch calls in hex format
• batchAllTx - Create a batchAll transaction of dispatch calls in hex format
• batchAllTxHex - Create a batchAll transaction of dispatch calls in hex format
• isValidAddress - Check if an address is a valid Ternoa address
• unFormatBalance - Format balance from number to BN

Fees

• getTxGasFee - Get the gas fee estimation for a transaction
• getTxTreasuryFee - Get the fee needed by Ternoa treasury for specific transaction services
• getTxFees - Get the total fees for a transaction hex
• checkFundsForTxFees - Check if a signed transaction sender has enough funds to pay transaction gas fees on transaction submit

Documentation

A detailed documentation was created here: ternoa-js documentation