@ton-community/assets-sdk
v0.0.5
Published
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](https://github.com/ton-community/flappy-bird-phaser).
Downloads
4,331
Keywords
Readme
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
orcreateNftCollection
/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 addressgetWallet
- same as above, but immediately opens the address as a jetton walletgetData
- gets the raw onchain data of the jettonsendDeploy
- sends a deploy message; this method is mostly for internal usesendMint
- sends a mint message; this method requires you to be the admin of the jettonsendChangeAdmin
- sends a message to change the admin; this method requires you to be the admin of the jettonsendChangeContent
- 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 walletsendTransfer
- send a message to transfer some tokens to another user; this method requires you to be the owner of the jetton walletsendBurn
- 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 transferparseTransfer
- 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 indexgetItem
- same as above, but open the acquired address as anNftItem
instancesendMint
- send a message to mint an item; this method requires you to be the collection adminsendBatchMint
- send a message to mint multiple items; this method requires you to be the collection adminsendDeploy
- send a message to deploy the collection, regular users should not normally use this methodsendChangeAdmin
- send a message to change the admin of the collection; this method requires you to be the collection adminsendChangeContent
- send a message to change the content of the collection; this method requires you to be the collection admingetData
- get raw onchain data of the jetton mintergetItemContent
- 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 itemgetData
- 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. |