Inscription standard

Deploy tokens

User, who wants to create a new token, must send a message to Master contract with the following comment

{
    "p":"gram-20",
    "op":"deploy", 
    "tick":"gram", 
    "max":"21000000000000000", 
    "limit":"100000000000",
    "start": "1702366656",
    "interval": "15",
    "penalty": "15"
}

Field	Description
p	Protocol name. gram-20 for this case
op	Operation. deploy for this case
tick	Token name. Must be unique (case insensitive) and 4 characters length. Allowed characters: a-z, 0-9, -
max	Maximum supply of tokens. Must be less than 340282366920938463463374607431768211455. For all operations before Fri Dec 29 2023 18:00:00 UTC following rule should be applied on the indexer side: The minimum possible value is 4 000 000. If the user provides a value less than 4 000 000, the indexer should use 4 000 000.
limit	Limit of tokens for one mint For all operations before Fri Dec 29 2023 18:00:00 UTC following rule should be applied on the indexer side: if max / limit < 4 000000 then limit value must be adjusted by the indexer to ceil(max / 4 000 000)
start	Start timestamp. Value 0 means that minting is started immediately. Maximal value is 30 days in seconds (start - now < 2592000)
interval	Interval between mints for 1 wallet in seconds. Minimal value is 4 seconds, maximal value is 86400
penalty	Penalty for early mint in seconds. If user minted tokens earlier than last_mint + interval, then he will not be able to mint tokens for interval + penalty seconds. Minimal value is 0, maximal value is 86400

After that, master contract checks the protocol and token name. Based on the token name, the address of the Root Token contract is calculated. Master deploys this contract and forwards the message to it. If there were no errors in the JSON, then the token creation will be tracked by the indexer.

In case of incorrect JSON format or incorrect protocol, any other user will be able to send the correct JSON and create a token. Only in this case will it be possible to start minting.

Master contract has method get_token_root_address(tick), which returns Root Token contract address by token name. It will be useful for frontend to get token contract address without indexer.

---

Mint tokens

For mint user must send a message to his token contract address with the following JSON

{
    "p":"gram-20",
    "op":"mint", 
    "tick":"gram", 
    "repeat":"1",
    "amt":"10000000000000000"
}

Field	Description
p	Protocol name. gram-20 for this case
op	Operation. mint for this case
tick	Token name
repeat	Number of mints. Minimal value is 1, maximal value is 24. In case of repeat > 1, protocol fee * repeat will be charged
amt	Amount of tokens to mint. Must be less than limit

Each token root contract has method get_user_address(user_wallet), which returns token contract address for each user by user wallet address. It means, that for each new token, token addresses for the same user will be different, which allows to filter requests more efficiently.

Contract will check interval between mints and penalize for early mint. So, if user minted tokens earlier than last_mint + interval, then he will not be able to mint tokens for interval + penalty seconds.

---

Transfer tokens

For transfer user must send a message to their token contract address with the following JSON

{
    "p":"gram-20",
    "op":"transfer", 
    "tick":"gram", 
    "to":"EQDKbjIcfM6ezt8KjKJJLshZJJSqX7XOA4ff-W72r5gqPrHF",
    "amt":"3000000000000000",
    "memo": "12345"
}

Field	Description
p	Protocol name. gram-20 for this case
op	Operation. transfer for this case
tick	Token name
to	Recipient address in friendly format
amt	Amount of tokens to transfer
memo	Memo. It can be used when transferring tokens to exchanges

---

Token metadata

The token's creator has the ability to set metadata, which includes title, description, URL and image. Images must be passed in base64 encoded format. Recommented payload is PNG image with 64x64 size with a transparent background.

All messages for metadata management must be sent to special smart-contract EQDkfHZs1hgap5v80GisRiP4xRQEvchINZ6Fpb_3V0MFnqiu. However, this smart-contract doesn't validate the sender is the creator of the token, it must be done on the indexer side.

{
    "p":"gram-20",
    "op":"metadata", 
    "tick":"gram", 
    "title":"GRAM-20 token",
    "description": "GRAM-20 is the cutting-edge platform designed to maximize the potential of inscriptions on the TON blockchain",
    "url": "https://docs.gram20.com/introduction/introduction",
    "image": "AAAAGGZ0eXBhdmlmAAAAAG1pZjFtaWFmAAAA0m1ldGEAAAAAAAAAIWhkbHIAAAAAAAAAAHBpY3QAAAAAAAAAAAAAAAAAAAAADnBpdG0AAAAAAAEAAAAeaWxvYwAAAABEAAABAAEAAAABAAAA8gAAAkMAAAAjaWluZgAAAAAAAQAAABVpbmZlAgAAAAABAABhdjAxAAAAAFZpcHJwAAAAOGlwY28AAAAUaXNwZQAAAAAAAABIAAAASAAAAAxhdjFDgT9AAAAAABBwaXhpAAAAAAMKCgoAAAAWaXBtYQAAAAAAAAABAAEDAYIDAAACS21kYXQSAAoJP9mjxy8BDQbQMrMEZGSM0EnE/z+wD9gEGgIRAAAAAAC7yI0EEEVA4i59Wdr8Hjz6G/gr5Nm8OnChV5EfiIW0spSKuHjP4CVgu/2OqOIVzO2FPY65/AEkwyvMJKzwHCzPvkdFV6vKfuvRfcgOSzvknjsEnMjDihyJaAnWIr83GbSGkjf2WJnnRCVEX2R6FKSbwHJWoB68rlSpzN1U5ZQhhaQ0/vNzY9bIY81ZGaQAw9ADTwZqVLeSOVcuKptFgrnP8iX7iYe96QjGaP3AsbjGEIN1/GJo3qza0EPNVIJq0DCcVC9u32nS7DPj6j9MDdAJ6vpvOUzsjvIPkCdY9vkWfYkxHdZyr8B4wRXUD6Bup0prUiAPbAfJbnIsX36FmwSlv6rp3LdDPPt5agZaCLGJajYOI1jAIXINi4FYczXjNUp7yOk4FbkujZTm2KklxTEINH2kvxF65J9gG96e4I3HVbx+wVAbtK6bcnmc9yr8iVzkqi6CtnYOm1DBuRvJ+r2ZIL84TPVESMMUppmkKx7ABdZdVyNnzJNL7ZzgK6apdcB2a3P6WVvPX9/8LbN2XnFaaEqucnsZInfR3w7Ib8pEfLeCJRbhR7HW9aUI2SR6lo1eVgntzB9jbThB/5pn3/emR//G1niHYKukHiJNd8fQI/+o8afKn1W/uetl5/2mxvetfYfmVIZ1sRZ4uezn5afCCGSt/cjrRxlPTv6hZDNYOtVrnHkIKk4Wf/5LIZ54fXx5hwv5BACSG1KepA1chlA="
}

Field	Description
p	Protocol name. gram-20 for this case
op	Operation. transfer for this case
tick	Token name
title	Token title (optional)
description	Token description (optional)
url	Token' page URL (optional)
image	Token image in base64 format (optional)

Some fields are optional which means the indexer should use the previous value (if any) when the field is absent.

---

Additional information

• Efficient management of inscription tokens on the TON blockchain is facilitated by this approach. Tokens are distributed across various contracts.

• Tokens will be measured in units with 9 decimals.

• For first-time token minting, users must deploy a user contract. Our service automates this deployment, so users don't need to handle it themselves.

• A mint is only successful if the transaction includes a completed JSON. This requires more gas but ensures fairness by minimizing the advantages of automated methods like bots.

• If the compute phase of an operation fails (indicated by an exit code not equal to 0, irrespective of the success field), indexers should not index the operation. This prevents spamming of indexers with failed operations.

• Minting is allowed only from the basic wallets. Wallet smart contract must be active after minting operation, in case of inactivation minting could be rejected.

• All JSON fields must be present, except for memo in the case of transfer operations.

• Operations (minting and transfers) must be executed in the order of ascending logical time (lt) from the user token contract transaction. If multiple transactions share the same lt within the same masterchain block, sort them by message hash.

• Transfers should be ignored for masterchain blocks with generate time before 24 Dec 2023 6:00am UTC

Advanced techinical information for developers

• Fields in JSON must be in the same order as in examples.

• All JSON payloads must be prefixed with data:application/json,

• JSON must be encoded as snake in cells without any spaces (it means all 1016 bits must be used).

• Master address is EQBoPPFXQpGIiXQNkJ8DpQANN_OmMimp5dx6lWjRZmvEgZCI