In this chapter, you will understand how to publish Smart Voucher (sub-ledger system) via FsTK API.

Smart Voucher is the application token under ERC-1376 Token.
In another word, each product and service (even digital identity) could be represented by individual Smart Voucher.

Table of Contents

  1. Prerequisite
  2. Encode the Transaction (publishing smart voucher)
  3. Decrypt the Ethereum Key JSON
  4. Sign the Ethereum Transaction
  5. Broadcast the Ethereum Transaction
  6. Confirm the Ethereum Transaction
  7. Confirm the Smart Voucher

Prerequisite

  1. Please sign up an account on https://test.fstk.io or https://engine.fstk.io.

    Notice account data are NOT shared across both platform.

    • test.fstk.io is Tokeneden built on Kovan Testnet for agile software development, testing & demo.
    • engine.fstk.io is official Tokeneden built on Ethereum Mainnet.
  2. Please take a look at your asset balances of ETHFSTFIL and FST Service Gas.

    Please remember that assets on test.fstk.io belongs to Kovan Testnet; assets on engine.fstk.io belongs to Mainnet.

    • ETH is Ether, a small amount will be given to new accounts on test.fstk.io.
    • FST is Funder Smart Token, a fundamental Utility Token within FST Network and will be given to new accounts on test.fstk.io.
    • FIL is FundersToken Initialisation License as Token Issuance License, 1 FIL will be given to new accounts on test.fstk.io.
    • FST Service Gas is the FsTK module usage fee for Token Issuer, balance is shown at User Profile on the top right corner.
  3. Please prepare your API testing tools.
  4. Understand how to retrieve Access Web Token (JWT).

    Please refer to Quick start Chapter 1.

  5. Complete Quick start.
  6. Confirm sufficient Ether (ETH) for ETH gas fee.
  7. Confirm sufficient FST Service Gas for module service fee (at least 600 FST Service Gas)
  8. Become Issuer (Token Issuer), please confirm token in get me.

Encode the Transaction (publishing smart voucher)

In any of following API calls, please remember to assign access token to authorization in http request header.

Hereinafter let’s take FST Sport Shop as the example.

  • Using multipart/form-data

    Assign operations with GraphQL query and variables

    • operations detail
      • name is the name of publishing Smart Voucher, at most 20 characters
      • symbol is the symbol of publishing Smart Voucher, at most 6 capital characters excluding prefix. The prefix must be the symbol of Smart Token, e.g. if symbol of Smart Token is ABC, then symbol of Smart Voucher can be ABC_TEST11.
      • consumable determines whether Smart Voucher is consumable. If true, then Consume is activated (still able to be transferred); if false, then Consume is de-activated (still able to be transferred).
      • totalSupply is the total supply of Smart Voucher. Notice that this number is an Int, unlike Token related values which has a multiple of 10^18.
      • price is an object showing how much Smart Token a Smart Voucher is equivalent to (i.e. the exchange ratio between Token & Voucher), also the initial price of Smart Voucher. Voucher can only be exchanged by Smart Token.
        • numerator is showing that how much wei a Smart Voucher is worth, e.g. a Smart Voucher with 123 Smart Token is equivalent to numerator = "123000000000000000000".
        • denominator is "1" in general. In special case, say numerator = "1000000000000000000" and denominator = "3", this means 3 Smart Voucher is worth 1 Smart Token, so that the pricing will be calculated in terms of fraction.
      • expiry is the expiry dat of Smart Voucher, with unit Unix time millisecond (ms), e.g. UTC+8 2019/12/31 is "1577807999000". Please notice that Unix time has no time zone, please adjust it to correspond to your current time zone.
      • description is the description of Smart Voucher.
      • proofOfContract is not required in operations, instead in form-data as another entry, is null here.

    proofOfContract is in pdf format to describe related legal agreements or rights of Smart Voucher, then stored and protected in IPFS.

    the summary of multipart/form-data is:

  • Using cURL

  • Response

    At the moment, API does not respond the value of consuming FST Service Gas. For calculation of FST Service Gas, please use this formula: Smart Voucher Total Supply * Effective days * 0.00003 FST Service Gaswith 600 FST Service Gas as the minimum fee.

    In response’s transaction, object will be used to sign payload, submitToken is also required for broadcasting signed transaction.

    Please remember that response will vary after each call, please use the latest response for next steps.

    e.g. Response like

    means the transaction will fail. We suggest to skip the following steps and check related resources of Transaction are correct first. e.g. ETH balance, FST Service Gas balance, Token balance, Voucher balance, … etc..

Decrypt the Ethereum Key JSON

Please notice the difference between password and passphrase in FsTK system. password is required to sign in Tokeneden; passphrase is required to decrypt Ethereum key JSON and sign the transaction.

Word usage may be different in other libraries, i.e. passphrase means password.

To start with, use get me to fetch ethereumKey like the following:

This is current user’s Ethereum key JSON, which includes encrypted private key (by passphrase). This can be safely stored but remain private unless necessary.

Owning private key means owning the Ethereum Account. Please securely store Ethereum key JSON and passphrase.

WARNING: If the passphrase of Ethereum key JSON is lost, the private key is lost and FsTK does not have users’ Ethereum key JSON passphrase.

  • Using JavaScript (Node.js)

    Install eth-key-lib

    This is the module import of ES6. If your node.js does not support it, please refer to Webpack (target = "node") and the followings:

    Minimal webpack.config.js

    Minimal package.json

    Install command line (please let index.js be the program entry point).

    If working on windows, please refer to node-gyp on windows.

  • Using Java

    Please refer to Web3j. Notice that loadCredentials in WalletUtils method with this overload:

    In another way, as web3j only provides File import, please pay attention to OS storage or use in-memory-fs in Java.

    Please to refer to Web3j sample codes.

  • Using C#

    Please refer to Nethereum. Please refer to Nethereum sample codes.

    Please use Account.PrivateKey to fetch private key from Account.

Sign the Ethereum Transaction

  • Using JavaScript
  • Using Java

    Please refer to Web3j. Notice that signMessage in TransactionEncoder, and please use the overload below since the chainId must be included in the signature process.

    Please refer to Web3j sample codes

  • Using C#

    Please refer to Nethereum. Please refer to SignTransaction in TransactionSigner, and please use the overload below since the chainId must be included in the signature process.

    Please refer to the section Nethereum.Web3.Accounts.AccountSignerTransactionManager.SignTransaction.

Broadcast the Ethereum Transaction

  • Using GraphQL (Insomnia recommended)

    Variables:

    data is the object from signing transaction with current user’s private key. In another word, signedTransaction is the hex string.

    submitToken is submitToken from Encode Ethereum Transaction.

  • Using cURL
  • Response

    transactionHash can be used to check whether transaction is confirmed in the next steps.

Confirm the Ethereum Transaction

  • Using GraphQL (Insomnia recommended)

    Variables:

    txHash is the transaction hash.

    Notice that transaction hash is unique on chain, but it may repeat when representing different transactions on different chain.

  • Using cURL
  • Response

    When remain in confirmations becomes 0, the transaction is confirmed.

    Notice that a confirmed transaction may not succeed. As on Blockchain, failed transaction is also a consensus. Please use Infura with ETH-JSON-RPC to fetch status (success/failure of transaction).

Confirm the Smart Voucher

Please refer to token.vouchers in get me (More details in Quick start Chapter 2).