gasfree-sdk-js

gasfree-sdk-js is a toolkit developed based on the GasFree API specification. It facilitates the integration of the non-gas TRC20 token transfer service for the web & browser extension platform.

This SDK is maintained by the gasfree.io developer community.

For more information, visit https://gasfree.io.

Key Features:

• Generate GasFree Addresses from User Addresses
• Generate GasFree Transfer Message Hash

Demo

• tronGenerateGasFreeAddress
• tronGetGasFreeTransactionJson
• tronGetGasFreeLedgerRawHash

Installing

add @gasfree/gasfree-sdk

npm install @gasfree/gasfree-sdk

or

yarn add @gasfree/gasfree-sdk

or

pnpm install @gasfree/gasfree-sdk

Usage

quick start

initialization:

const tronGasFree = new TronGasFree({
  chainId: Number('0x2b6653dc'), // use mainnet default config
});

generate gas free address:

import { TronGasFree } from '@gasfree/gasfree-sdk';

try {
  const userAddress = 'your tron wallet address';
  const tronGasFree = new TronGasFree({
    chainId: Number('0x2b6653dc'), // use mainnet default config
  });
  const tronGasFreeAddress = tronGasFree.generateGasFreeAddress(userAddress);
} catch (error) {
  console.log(error);
}

get standard TIP712 gas free transaction json object:

try {
  const tronGasFree = new TronGasFree({
    chainId: Number('0x2b6653dc'), // use mainnet default config
  });
  const transactionJson = tronGasFree.assembleGasFreeTransactionJson({
    token: 'transaction token contract address',
    serviceProvider: 'gas free transaction service provider',
    user: 'your tron wallet address, NOT your gas free address',
    receiver: 'tron receiver address, it can be a wallet address or a gasfree contract address',
    value: 'transfer value, decimal string number',
    maxFee: 'max transfer gas fee, decimal string number',
    deadline: 'timestamp, transaction deadline',
    version:
      'version of the signature algorithm used by gasfree offline transaction, the current version is 1',
    nonce: 'gas free transaction nonce, decimal string number',
  });
} catch (error) {}

initialization

use Tron mainnet default config:

const tronGasFree = new TronGasFree({
  chainId: Number('0x2b6653dc'),
});

if you want to use testnet config:

const tronGasFree = new TronGasFree({
  chainId: Number('0xcd8690dc'), // nile
});

or

const tronGasFree = new TronGasFree({
  chainId: Number('0x94a9059e'), // shasta
});

If you have your own GasFreeController contract, or your own chain:

const tronGasFree = new TronGasFree({
  chainId: 0, // your chainId, number
  gasFreeController:
    'your gas free controller address contract, should deployed on the chain in advance',
  beacon: 'your beacon',
  creationCode: 'your GasFreeController creation code',
});

generate GasFree address

import { TronGasFree } from '@gasfree/gasfree-sdk';

try {
  const userAddress = 'your tron wallet address';
  const tronGasFree = new TronGasFree({
    chainId: Number('0x2b6653dc'), // use mainnet default config
  });
  const tronGasFreeAddress = tronGasFree.generateGasFreeAddress(userAddress);
} catch (error) {
  console.log(error);
}

different chains and different GasFreeControllers will result in inconsistent GasFree addresses.

const userAddress = 'your tron wallet address';
const tronGasFree = new TronGasFree({
  chainId: Number('0xcd8690dc'), // nile
});
const tronGasFreeAddress2 = tronGasFree.generateGasFreeAddress(userAddress);
// tronGasFreeAddress2 is different from tronGasFreeAddress

Get standard TIP712 gas free transaction json object

try {
  const tronGasFree = new TronGasFree({
    chainId: Number('0x2b6653dc'), // use mainnet default config
  });
  const transactionJson = tronGasFree.assembleGasFreeTransactionJson({
    token: 'transaction token contract address',
    serviceProvider: 'gas free transaction service provider',
    user: 'your tron wallet address, NOT your gas free address',
    receiver: 'tron receiver address, it can be a wallet address or a gasfree contract address',
    value: 'transfer value, decimal string number',
    maxFee: 'max transfer gas fee, decimal string number',
    deadline: 'timestamp, transaction deadline',
    version:
      'version of the signature algorithm used by gasfree offline transaction, the current version is 1',
    nonce: 'gas free transaction nonce, decimal string number',
  });
} catch (error) {}

normal GasFree signature

import TronWeb from 'tronweb';
import { TronGasFree } from '@gasfree/gasfree-sdk';

const PRIVATE_KEY = 'your private key';

try {
  const tronGasFree = new TronGasFree({
    chainId: Number('0x2b6653dc'), // use mainnet default config
  });

  const { domain, types, message } = tronGasFree.assembleGasFreeTransactionJson({
    token: 'transaction token contract address',
    serviceProvider: 'gas free transaction service provider',
    user: 'your tron wallet address, NOT your gas free address',
    receiver: 'tron receiver address, it can be a wallet address or a gasfree contract address',
    value: 'transfer value, decimal string number',
    maxFee: 'max transfer gas fee, decimal string number',
    deadline: 'timestamp, transaction deadline',
    version:
      'version of the signature algorithm used by gasfree offline transaction, the current version is 1',
    nonce: 'gas free transaction nonce, decimal string number',
  });

  const res = await TronWeb.Trx._signTypedData(domain, types, message, PRIVATE_KEY);
} catch (error) {}

ledger GasFree signature

import { TronGasFree } from '@gasfree/gasfree-sdk';
import AppTrx from '@ledgerhq/hw-app-trx';
import TransportWebHID from '@ledgerhq/hw-transport-webhid';

try {
  const tronGasFree = new TronGasFree({
    chainId: Number('0x2b6653dc'), // use mainnet default config
  });
  const { permitTransferMessageHash } = tronGasFree.getGasFreeLedgerRawHash({
    message: {
      token: 'transaction token contract address',
      serviceProvider: 'gas free transaction service provider',
      user: 'your tron wallet address, NOT your gas free address',
      receiver: 'tron receiver address, it can be a wallet address or a gasfree contract address',
      value: 'transfer value, decimal string number',
      maxFee: 'max transfer gas fee, decimal string number',
      deadline: 'timestamp, transaction deadline',
      version:
        'version of the signature algorithm used by gasfree offline transaction, the current version is 1',
      nonce: 'gas free transaction nonce, decimal string number',
    },
  });
  const transport = await TransportWebHID.create();
  const app = new AppTrx(transport);
  const path = 'you ledger address path';
  const res = await app.signTransactionHash(path, permitTransferMessageHash);
} catch (error) {}

Running the tests

The project includes a suite of tests for the Tron GasFree sdk. To run these tests, use the following command:

pnpm test

Local build

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

• Node.js >= 18.19.0
• pnpm >= 7.32.0
• TypeScript >= 4.9.5

Build

1. Install pnpm

This project recommends using pnpm as the build tool Make sure node is installed:

Make sure the node version meets the requirements:

node -v

and install pnpm:

npm i -g pnpm

2. Clone the repository

You can use git clone to download or download the code directly

3. Install dependencies

pnpm install

4. Compile TypeScript files

pnpm build

Built With

• TypeScript
• Node.js

License

This project is licensed under the Apache License Version 2.0 - see the LICENSE file for details