TF Grid API client

Client provides all the tooling around tfchain and its modules, including creating entities, twins, farms.. etc

Installation

npm install tfgrid-api-client

API Definition

Available methods:

init

inits the client and returns a promise

const Client = require('tfgrid-api-client')

const url = "urlToWebsocket"
const mnemonic = "some words"

const client = new Client(url, mnemonic)

try {
  await client.init()
} catch (err) {
  return err
}

createEntity

Creates an entity based on following information:

• name: name of the entity.
• countryID: ID of the country where the entity is located
• cityID: ID of the city where the entity is located
• callback: optional callback

const name = 'foobar'
const countryID = 1
const cityID = 1

// This call wont be blocking and will return the block where the tx is included
const block = await client.createEntity(name, countryID, cityID, callback: optional)
console.log(`Transaction included in block with hash: ${block.toHex()}`)

Note: An entity is always linked to a private keypair, only one entity can be created per keypair.

updateEntity

updates an entity based on following information:

• name: name of the entity.
• countryID: ID of the country where the entity is located
• cityID: ID of the city where the entity is located
• callback: optional callback

// This call wont be blocking and will return the block where the tx is included
const block = await client.updateEntity(name, countryID, cityID, callback: optional)
console.log(`Transaction included in block with hash: ${block.toHex()}`)

getEntityByID

Fetches an entity from storage based on an ID.

const entity = await client.getEntityByID(1)

listEntities

Fetches all entities from storage.

const entity = await client.listEntities()

deleteEntity

Deletes the entity linked to the private key.

await client.deleteEntity(callback: optional)

createTwin

Creates a twin based on following information:

• peerID: Yggdrassil peer ID.
• callback: optional callback

const peerID = '2a02:1812:1443:300:7913:de17:4c83:ecb2'

// This call wont be blocking and will return the block where the tx is included
const block = await client.createTwin(peerID, callback: optional)
console.log(`Transaction included in block with hash: ${block.toHex()}`)

Note: A twin is by default anonymous, check addTwinEntity to add an entity to a twin.

getTwinByID

Fetches twin from storage based on an ID.

const twin = await client.getTwinByID(1)

listTwins

Fetches all twins from storage.

const entity = await client.listTwins()

deleteTwin

Deletes a twin from storage based on an ID. Only the creator of this twin can delete this twin.

await client.deleteTwin(1)

addTwinEntity

Add an entity to a twin. The entity that is being added must sign a message composed of the twinID and entityID. Only the twin's owner can add an entity to it's twin.

• entityID: entity ID to add.
• twinID: twin ID to update.
• signature: signature signed by private key of entity
• callback: optional callback

example:

const entityID = 0
const twinID = 0

// the entity that owns this entity can sign this with his private key
const signedMessage = await client.sign(entityID, twinID)


// This call wont be blocking and will return the block where the tx is included
const block = await client.addTwinEntity(twinID, entityID, signedMessage, callback)
console.log(`Transaction included in block with hash: ${block.toHex()}`)

If the signature of the signedMessage is valid, this entity id will be added to this twin.

removeTwinEntity

Removes an entity from a twin. Only the twin's owner can remove an entity from it's twin.

• entityID: entity ID to remove.
• twinID: twin ID to update.
• callback: optional callback

example:

// This call wont be blocking and will return the block where the tx is included
const block = await client.removeTwinEntity(twinID, entityID, callback)
console.log(`Transaction included in block with hash: ${block.toHex()}`)

sign

Sign an entityID and twinID combination and returns a signed message.

• entityID: entity ID.
• twinID: twin ID.

const signedMessage = await client.sign(entityID, twinID)

vest

Vest an amount of tokens for a specific duration, if the tft price provided is equal to the real tft price. It unlocks the current and previous vesting months.

locked, perBlock, startingBlock, tftPrice

• locked: amount of tokens to lock
• perBlock: amount of tokens that unlock every block (1 block = 6 seconds)
• startingBlock: block number to start the vesting on
• tftPrice: price of tft that will trigger unlock condition (decimal number eg: 0.50)
• callback: optional callback

example:

// This call wont be blocking and will return the block where the tx is included
const block = await client.vest(locked, perBlock, startingBlock, tftPrice, callback)
console.log(`Transaction included in block with hash: ${block.toHex()}`)

getPrice

Fetches the TFT Price.

const price = await client.getPrice()

getBalance

Fetches your account's balance.

const balance = await client.getBalance()

tfStoreGet

Set a value in tf key-value store

await client.tfStoreSet("name", "Ashraf", (res) => {
  if (res instanceof Error) {
    console.log(res)
  }
});

tfStoreGet

console.log(await client.tfStoreGet("name"))

Example callback function

// This call will block until status is Finalized and tx is included in a block and validated
await client.createEntity(name, countryID, cityID, (res) => {
  if (res instanceof Error) {
    console.log(res)
    exit(1)
  }

  const { events = [], status } = res
  console.log(`Current status is ${status.type}`)

  if (status.isFinalized) {
    console.log(`Transaction included at blockHash ${status.asFinalized}`)

    // Loop through Vec<EventRecord> to display all events
    events.forEach(({ phase, event: { data, method, section } }) => {
      console.log(`\t' ${phase}: ${section}.${method}:: ${data}`)
    })
    exit(1)
  }
})