Skip to content

Latest commit

 

History

History
223 lines (150 loc) · 23.5 KB

hedera-service-solidity-libraries.md

File metadata and controls

223 lines (150 loc) · 23.5 KB
Raw

Hedera Service Solidity Libraries

Hedera Token Service

Hedera Token Service integration allows you to write token transactions natively in Solidity smart contracts. There are a few Solidity source files available to developers.

The Hedera Token Service Solidity file provides the transactions to interact with tokens created on Hedera. The Hedera Response Codes contract provides the response codes associated with network errors. The IHedera Token Service is a supporting library for the Hedera Token Service Solidity file. You can grab these libraries here to add to your project and import them to your Solidity contract. Please see the example file below.

{% code title="ContractExample.sol" %}

// SPDX-License-Identifier: GPL-3.0

pragma solidity >=0.7.0 <0.9.0;

import "./HederaTokenService.sol";
import "./HederaResponseCodes.sol";

contract contractExample is HederaTokenService {
...
int response = HederaTokenService.transferToken(tokenAddress, msg.sender, address(this), amount);
...
}

{% endcode %}

{% hint style="info" %} Note: Although the IHederaTokenService.sol file is not imported in the contract, you will need it in your project directory for the supporting libraries to reference. {% endhint %}

HederaTokenService.sol API Docs

Create Tokens

{% hint style="info" %} HIP-358: Token create precompile is live on previewnet and testnet. The TokenCreateContract example contains four examples for how to create a token using the token create solidity libraries. {% endhint %}

createFungibleToken(token, initialTotalSupply, decimals)

A transaction that creates a fungible token. Returns the new token address.

Param Type Description
token IHederaTokenService.HederaToken memory The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.
initialTotalSupply uint Specifies the initial supply of tokens to be put in circulation. The initial supply is sent to the Treasury Account. The supply is in the lowest denomination possible.
decimals uint The number of decimal places a token is divisible by.

createFungibleTokenWithCustomFees(token, initialTotalSupply, decimals, fixedFees, fractionalFees)

A transaction that creates a fungible token with custom fees. Returns the new token address.

Param Type Description
token IHederaTokenService.HederaToken memory The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.
initialTotalSupply uint Specifies the initial supply of tokens to be put in circulation. The initial supply is sent to the Treasury Account. The supply is in the lowest denomination possible.
decimals uint The number of decimal places a token is divisible by.
fixedFees IHederaTokenService.FixedFee[] List of fixed fees to apply to the token.
fractionalFees IHederaTokenService.FractionalFee[] List of fractional fees to apply to the token.

createNonFungibleToken(token)

Creates a non fungible token. Returns the new token address.

Param Type Description
token IHederaTokenService.HederaToken memory The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.

createNonFungibleTokenWithCustomFees(token, fixedFees, fractionalFees)

Creates a non fungible token with custom fees. Returns the new token address.

Param Type Description
token IHederaTokenService.HederaToken memory The basic properties of the token being created. This includes the token name, symbol, treasury account, keys, expiry, etc.
fixedFees IHederaTokenService.FixedFee[] List of fixed fees to apply to the token.
fractionalFees IHederaTokenService.FractionalFee[] List of fractional fees to apply to the token.

Transfer Tokens

cryptoTransfer(tokenTransfers)

A transaction that transfers the provided list of tokens.

ABI Version: 2

Param Type Description
tokenTransfers IHederaTokenService.TokenTransferList[] memory The list of token transfers

transferToken(token, sender, receiver, amount)

Transfers tokens where the calling account/contract is implicitly the first entry in the token transfer list, where the amount is the value needed to zero balance the transfers. The account address sending the token is required to sign the transaction.

ABI Version: 1

Param Type Description
token address The token ID to transfer to/from. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
sender address The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
receiver address The address of the receiver of the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amount int64 Non-negative value of the token to send. A negative value will result in a failure.

transferTokens(token, accountIds, amount)

Initiates a fungible token transfer. Not applicable to non-fungible tokens.

ABI Version: 1

Param Type Description
token address The token ID to transfer. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
accountIds address[] memory Hedera accounts to do a transfer to/from. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amounts int64[] memory Non-negative value to send. A negative value will result in a failure.

transferNFT(token, sender, receiver, serialNum)

Transfers tokens where the calling account/contract is implicitly the first entry in the token transfer list, where the amount is the value needed to zero balance the transfers. The address sending the token is required to sign the transaction.

ABI Version: 1

Param Type Description
token address The token to transfer to/from.
sender address The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
receiver address The address of the receiver of the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
serialNum int64 The serial number of the NFT to transfer.

transferNFTs(token, sender, receiver, serialNumber)

Initiates a non-fungible token transfer

ABI Version: 1

Param Type Description
token address The ID of the token to transfer. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
sender address[] memory The address sending the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
receiver address[] memory The address of the receiver of the token. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
serialNumber int64 The serial number of the nft sent by the same index at sender.

Mint Tokens

mintToken(token, amount, metadata)

Mints an amount of the token to the defined treasury account.

ABI Version: 2

Param Type Description
token address The Hedera token to mint. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amount


uint64

Applicable to FUNGIBLE TOKENS ONLY.

The amount to mint to the Treasury Account. Amount must be a positive non-zero number represented in the lowest denomination of the token. The new supply must be lower than 2^63.
metadata bytes[] memory

Applicable to NON-FUNGIBLE TOKENS ONLY.
Maximum allowed size of each metadata is 100 bytes

Burn Tokens

burnToken(token, amount, serialNumbers)

Burns an amount of the token from the defined treasury account.

ABI Version: 2

Param Type Description
token address The token to burn. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
amount uint64

Applicable to FUNGIBLE TOKENS ONLY.

The amount to burn from the Treasury Account. Amount must be a positive non-zero number, not bigger than the token balance of the treasury account (0; balance], represented in the lowest denomination.
serialNumbers int64[]

Applicable to NON-FUNGIBLE TOKENS ONLY.

The list of serial numbers to be burned.

Associate Tokens

associateToken(account, tokens)

Associates the provided account with the provided tokens. Must be signed by the account that is being associated with the token.

ABI Version: 2

Param Type Description
account address The account to be associated with the provided tokens. The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
token address[] memory

The list of tokens to be associated with the provided account.


In the case of non-fungible tokens, once an account is associated, it can hold any number of NFTs (serial numbers) of that token type.

The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.

Dissociate Tokens

dissociateToken(account, token)

Dissociates the provided account with the provided token. Must be signed by the provided Account's key.

ABI Version: 2

Param Type Description
account address

The Hedera account to be dissociated from the provided token.

The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.
token address

The token to be dissociated from the provided account.

The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.

dissociateTokens(account, tokens)

Dissociates the provided account with the provided token. Must be signed by the account the token is being dissociated from.

ABI Version: 2

Param Type Description
account address The account to be dissociated from the provided tokens
tokens address[] memory

The list of tokens to be dissociated from the provided account.

The address is a mapping of shard.realm.number (0.0.x) into a 20 byte Solidity address.

Gas Cost

{% content-ref url="../../../core-concepts/smart-contracts/gas-and-fees.md" %} gas-and-fees.md {% endcontent-ref %}

Examples

{% content-ref url="../../../getting-started/try-examples/deploy-a-contract-using-the-hedera-token-service.md" %} deploy-a-contract-using-the-hedera-token-service.md {% endcontent-ref %}