ton-community / assets-sdk

assets-sdk

Assets SDK provides developer friendly APIs to help interact game developers with different assets on TON, such as NFTs/SBTs and jettons. An example game using it can be found here.

Installation

Install the package using npm:

npm i @ton-community/assets-sdk

If you are using the SDK as a CLI tool, you need to set up the environment first. You can do that by running the following command:)

npx assets-cli setup-env

Usage

In order to start using this SDK, you need to acquire an instance of AssetsSDK in your code. That will require specifying a storage (we currently support Pinata and S3 out of the box, but you can implement your own using our interface), an API (mainnet or testnet), and a wallet (V4 is supported out of the box). For example:

import {AssetsSDK, PinataStorageParams, createApi, createSender, createWalletV4, importKey} from "@ton-community/assets-sdk";

// create an instance of the TonClient4
const NETWORK = 'testnet';
const api = await createApi(NETWORK);

// create a sender from the wallet (in this case, Highload Wallet V2)
const keyPair = await importKey(process.env.MNEMONIC);
const sender = await createSender('highload-v2', keyPair, api);

// define the storage parameters (in this case, Pinata)
const storage: PinataStorageParams = {
    pinataApiKey: process.env.PINATA_API_KEY!,
    pinataSecretKey: process.env.PINATA_SECRET!,
}

// create the SDK instance
const sdk = AssetsSDK.create({
    api: api,          // required, the TonClient4 instance
    storage: storage,  // optional, the storage instance (Pinata, S3 or your own)
    sender: sender,    // optional, the sender instance (WalletV4, TonConnect or your own)
});

(This is taken directly out of our example, and you can find more in that directory)

Here, you would pass your Pinata keys and the wallet mnemonic (space separated) as env variables.

Don't use the mnemonic in browser environment, use TonConnect instead.

After you do that, you can:

• create a jetton minter or an NFT/SBT collection (as in the example mentioned above) using the methods createJetton or createNftCollection/createSbtCollection
• open an existing jetton minter, jetton wallet, NFT/SBT collection or NFT/SBT item in order to perform some action on them (mint, transfer, burn, etc)

Using with TonConnect

The SDK can be used with TonConnect to send messages to the TON blockchain. To do that, you need to create a TonConnectProvider instance and pass it to the SDK. For example:

// create a new instance of TonConnectUI
const provider = new TonConnectUI();
// create a new instance of TonConnectProvider
const sender = new TonConnectProvider(provider);

const sdk = await AssetsSDK.create({
    // provide the sender to the SDK  
    sender,
});

Now, the SDK will use TonConnect to send messages to the TON blockchain.

Storing to cells and loading from cells

The SDK also provides a way to store messages in cells and load them from cells. For example:

Storing a message in a cell

import {beginCell} from "@ton/core";
import {storeJettonMintMessage, loadJettonMintMessage} from "@ton-community/assets-sdk";

// storing a jetton mint message in a cell
const mintMessage: Cell = beginCell()
    .store(storeJettonMintMessage({
        to: Address.parse('RECIEVER_ADDRESS'),
        amount: toNano(1)
    })).endCell()
// getting the base64 representation of the boc
mintMessage.toBoc().toString('base64')

Loading a message from a cell

import {Cell} from "@ton/core";
import {loadJettonMintMessage} from "@ton-community/assets-sdk";

// parsing a jetton mint message in a boc base64 to a cell
const mintMessageCell: Cell = Cell.fromBase64('BASE64_BOC');
// loading the message from the cell
const mintMessage: JettonMintMessage = loadJettonMintMessage(mintMessageCell);

Jettons

Creating a jetton minter

Call the createJetton method on the SDK instance, passing JettonContent (all possible fields are uri, name, description, image, imageData, symbol, decimals, amountStyle, renderType, see TEP-64 for their description), and any options, such as onchainContent (to put the metadata onchain), adminAddress (to make a different address the admin), premint (to mint some tokens immediately on deploy), and value (to specify the amount of TON sent as fee). For example:

const jetton = await sdk.createJetton({
    name: 'Test jetton',
    decimals: 9,
    description: 'Test jetton description',
    symbol: 'TEST',
}, {
    premint: {
        to: sdk.sender?.address!,
        amount: toNano('100'),
    },
});

Open an existing jetton minter

Call the openJetton method with the address of the jetton that you wish to open, for example:

const jetton = sdk.openJetton(Address.parse('EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c'));

Using the jetton minter instance

Once you have a Jetton instance acquired by either creating it or opening one, you can perform the following actions:

• getWalletAddress - get a user's jetton wallet address
• getWallet - same as above, but immediately opens the address as a jetton wallet
• getData - gets the raw onchain data of the jetton
• sendDeploy - sends a deploy message; this method is mostly for internal use
• sendMint - sends a mint message; this method requires you to be the admin of the jetton
• sendChangeAdmin - sends a message to change the admin; this method requires you to be the admin of the jetton
• sendChangeContent - sends a message to change the content of the jetton; this method requires you to be the admin of the jetton

Using the jetton wallet instance

You can acquire a JettonWallet instance either by calling the openJettonWallet on the SDK instance with the address of a known jetton wallet, or by calling getWallet on a Jetton minter instance.

You can then use it to perform the following actions:

• getData - get the raw onchain data of the wallet
• sendTransfer - send a message to transfer some tokens to another user; this method requires you to be the owner of the jetton wallet
• sendBurn - send a message to burn some tokens; this method requires you to be the owner of the jetton wallet

You can also use the JettonWallet class itself to do the following:

• parseTransferBody - parse the body of a transfer transaction to retrieve the parameters of the transfer
• parseTransfer - same as the above, but parse the entire transaction instead of just its body to retrieve additional parameters

NFTs

Creating an NFT/SBT collection

Call the createNftCollection/createSbtCollection, specifying in the first argument the collectionContent (all possible fields are uri, name, description, image, imageData, see TEP-64 for their descriptions), passing any options (same as with jettons) as the second argument. For example:

const collection = await sdk.createNftCollection({
    collectionContent: {
        name: 'Test collection',
        description: 'Test collection description',
    },
    commonContent: 'https://example.com/nft-items/',
});

Open an existing NFT/SBT collection

Call the openNftCollection/openSbtCollection method with the address of the collection that you wish to open, for example:

const collection = sdk.openNftCollection(Address.parse('EQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAM9c'));

Using the NFT/SBT collection instance

Once you have an NftCollection/SbtCollection instance, you can perform the following actions:

• getItemAddress - get the item's address by its index
• getItem - same as above, but open the acquired address as an NftItem instance
• sendMint - send a message to mint an item; this method requires you to be the collection admin
• sendBatchMint - send a message to mint multiple items; this method requires you to be the collection admin
• sendDeploy - send a message to deploy the collection, regular users should not normally use this method
• sendChangeAdmin - send a message to change the admin of the collection; this method requires you to be the collection admin
• sendChangeContent - send a message to change the content of the collection; this method requires you to be the collection admin
• getData - get raw onchain data of the jetton minter
• getItemContent - get the full item content using the item index and individual item content

Using the NFT/SBT item instance

You can acquire an NftItem instance either by calling the getItem method on a collection instance, or by calling openNftItem on the SDK instance.

Using the instance, you can do the following:

• sendTransfer - send a message to transfer the item; requires you to be the owner of the item, will not work on an SBT item
• getData - get the raw onchain data of the item

CLI usage

It's also an option to use the SDK as a CLI tool. To do that, pick one of the following options:

# global installation
npm i -g @ton-community/assets-sdk
assets-cli COMMAND

# local installation
npm install --save-dev @ton-community/assets-sdk
npx assets-cli COMMAND

Commands

Before running other commands, please run assets-cli setup-env first.

Command	Description
assets-cli setup-env	Sets up the environment for the application.
assets-cli get-wallet-state	Print your wallet type and balance.
assets-cli cancel-nft-sale	Cancel an existing NFT sale.
assets-cli deploy-jetton	Create and deploy a new jetton.
assets-cli deploy-nft-collection	Create and deploy a new NFT collection.
assets-cli get-jetton	Print details of an existing jetton.
assets-cli get-jetton-balance	Print balance of a specific jetton wallet.
assets-cli get-nft-collection	Print details of an existing NFT collection.
assets-cli get-nft-collection-item	Print details of an item from the NFT collection.
assets-cli get-nft-collection-items	Print details of all items from the NFT collection.
assets-cli get-nft-item	Print details of an NFT item.
assets-cli get-nft-sale	Print details of an NFT sale.
assets-cli mint-jetton	Mint jettons and sends them to the wallet.
assets-cli mint-nft	Mint NFT to the wallet.
assets-cli mint-sbt	Mint SBT to the wallet.
assets-cli put-nft-for-sale	Puts an NFT item for sale.
assets-cli transfer-jetton	Transfer jetton to another wallet.
assets-cli transfer-nft	Transfer NFT to another wallet.
assets-cli transfer-ton	Transfer TON to another wallet.

License

MIT

assets-sdk's Issues

Feature Request: setting tonclient api key

I'm using TonCenter. and i want to be able to set my TonCenter Api key to use it as the client

SDK just hangs when creating NFT collection

When runnnig:

 const result = await sdk.deployNftCollection(
    {
      collectionContent: {
        name: collectionName,
        description: 'An event',
      },
      commonContent: baseUrl,
    },
    { adminAddress, value: toNano(0.03) }

The code just hangs. It hangs on the following line:

 async deployNftCollection(content, options) {
        if (!this.sender) {
            throw new Error('Sender must be defined');
        }
        const adminAddress = options?.adminAddress ?? this.sender?.address;
        if (adminAddress === undefined) {
            throw new Error('Admin address must be defined in options or be available in Sender');
        }
        console.log("before open")
        const collection = this.api.open(NftCollection_1.NftCollection.createFromConfig({
            admin: adminAddress,
            content: (0, core_1.beginCell)()
                .storeRef(await this.contentToCell((0, content_2.nftContentToInternal)(content.collectionContent), options?.onchainContent ?? false))
                .storeRef((0, core_1.beginCell)().storeStringTail(content.commonContent))
                .endCell(),
            royalty: options?.royaltyParams,
        }, NftCollection_1.NftCollection.code, WORKCHAIN, this.contentResolver));
        console.log("after open")
        if (typeof options?.premintItems?.length === 'number' && options?.premintItems.length > 0) {
            await collection.sendBatchMint(this.sender, options?.premintItems, {
                value: options?.value,
                queryId: options?.queryId
            });
        }
        else {
            console.log("before sendDeploy")
            await collection.sendDeploy(this.sender, options?.value); // Here
            console.log("after sendDeploy")
        }
        return collection;
    }

I am using testnet.

Implement Amazon S3 storage

This SDK is storage-agnostic thanks to this interface, however, currently only Pinata is implemented as a storage provider. Amazon S3 is another popular storage provider, and help is needed to implement the Storage interface using it.

Error deploy-jetton failed: upload image: [object Object]

I have an error when I run assets-cli deploy-jetton
Attempt 1 failed: upload image: [object Object]
Attempt 2 failed: upload image: [object Object]
Attempt 3 failed: upload image: [object Object]
Error: Exceeded number of retries
at retry (C:..\npm\node_modules@ton-community\assets-sdk\dist\cli\common.js:176:11)
at async Object.main (C:..\npm\node_modules@ton-community\assets-sdk\dist\cli\deploy-jetton.js:79:23)
I use pinata storage and IPFS gateway

Create NFT examples

There is currently an example that shows how to create an SDK instance and create a jetton. There is a need for a similar example that would show how to create an NFT collection, mint some items, and transfer an item. Here are the NFT contract wrapper sources with all their methods.

Add compressed nft/sbt support

Feature Request createHighloadV3

https://docs.ton.org/participate/wallets/contracts#highload-wallet-v3

how to migrate @ton-community/gamefi-sdk to @ton-community/assets-sdk

need guide on migrate @ton-community/gamefi-sdk to @ton-community/assets-sdk

Error: Cannot find module 'boxen'

I try code transfer-jettons.ts and get this error.

npx ts-node .\transfer-jettons.ts
Error: Cannot find module 'boxen'

Cannot load metadata of NFT item when use deployNftCollection with not empty commonContent

I have a problem with commonContent. I cannot load metadata of NFT item when use deployNftCollection with NOT empty commonContent, but it work when commonContent = ''.

Can you guy help me explain about this case? Many thanks :)

Here is my code:

Deploy NFT Collection

...
const commonContent = await sdk.storage.uploadFile(
  Buffer.from(JSON.stringify(content), "utf-8")
);

const collection = await sdk.deployNftCollection(
  {
    collectionContent: content,
    commonContent: commonContent, // Issue here
  },
  {
    adminAddress: adminAddress,
  }
);
...

Deploy NFT Item:

...
const collection = sdk.openNftCollection(Address.parse(COLLECTION));

const content = Buffer.from(
  JSON.stringify({
    name: "Test NFT 1",
    description: "This is a test NFT 1",
    image: uploadedImageURL,
    "attributes":[{"trait_type":"Awesomeness","value":"Super cool"}],
  }), "utf-8"
);

const metadataURL = await sdk.storage.uploadFile(content);

const { nextItemIndex: index } = await collection.getData();
await collection.sendMint(sender, {
  index: index,
  owner: sdk.sender?.address!,
  individualContent: metadataURL,
});
...

Extend Jetton example

There is currently an example showing how to create a jetton using the SDK. However, it doesn't show all the features that the SDK offers when it comes to jettons, for example it doesn't show how to open an existing jetton, how to mint more tokens, how to transfer tokens, etc, so help is needed to add these features to the example.