Skip to content

Latest commit

 

History

History
494 lines (387 loc) · 10.9 KB

tok_ctrt_split.md

File metadata and controls

494 lines (387 loc) · 10.9 KB
Raw

Token Contract V1 With Split

Introduction

Token Contract V1 with Split is the twin case for Token Contract V1 Without Split. The token unit can be updated at any time after the contract instance is registered.

Usage with JavaScript SDK

Registration

The example below shows registering an instance of Token Contract V1 With Split where the max amount is 100 & the unit is 100.

import * as jv from '@virtualeconomy/js-vsys';

// acnt: Account

const tc = await jv.TokCtrtWithSplit.register(
  acnt, // by
  10000, // max
  100, // unit
  'test token with split', // tokDescription
  'register token' // ctrtDescription
);

console.log('ctrtID:', tc.ctrtId.data);
console.log('tokID: ', tc.getTokId(await tc.getLastTokIdx()).data);

Example output

ctrtID: CEu9aFoVwdApYBAPFy4hTYc2NUJRzoL5VYc
tokID:  TWsi8XxwJqrHZTbjYMj4f3nHCTE37oRXRjfHCwahj

From Existing Contract

tokCtrtId is the ctrtID of previously registered token.

import * as jv from '@virtualeconomy/js-vsys';

// ch: Chain

const tokCtrtId = 'CEu9aFoVwdApYBAPFy4hTYc2NUJRzoL5VYc';
const tc = new jv.TokCtrtWithSplit(tokCtrtId, ch);

Querying

Issuer

The address that has the issuing right of the Token contract instance.

// tc: TokCtrtWithSplit

console.log(await tc.getIssuer());

Example output

Addr { data: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q' }

Maker

The address that made this Token contract instance.

// tc: TokCtrtWithSplit

console.log(await tc.getMaker());

Example output

Addr { data: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q' }

Token ID

The token ID of the token defined in the token contract instance.

Note that theoretically a token contract instance can have multiple kinds of token, it is restricted to 1 kind of token per token contract instance. In other word, the token ID is of the token index 0.

// tc: TokCtrtWithSplit

console.log(tokB.getTokId(0));

Example output

TokenID { data: 'TWsi8XxwJqrHZTbjYMj4f3nHCTE37oRXRjfHCwahj' }

Unit

The unit of the token defined in this token contract instance.

// tc: TokCtrtWithSplit

console.log(await tc.getUnit());

Example output

100

Token Balance

Query the balance of the token defined in the contract for the given user.

// tc: TokCtrtWithSplit
// acnt: Account

console.log(await tc.getTokBal(acnt.addr.data));

Example output

Token { data: BigNumber { s: 1, e: 5, c: [ 250000 ] }, unit: 100 }

Actions

Supersede

Transfer the issuer role of the contract to a new user.

The maker of the contract has the privilege to take this action.

// acnt0: Account
// acnt1: Account
// tc: TokCtrtWithSplit

let resp = await tc.supersede(
  acnt0, // by
  acnt1.addr.data, // newIssuer
  'giving rights to issue to acnt1' // attachment
);
console.log(resp);

Example output

{
  type: 9,
  id: '8y1Yrg44hHh4uC8kCVqmTFGHyvK8PYfFafdsKjdF7k7p',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654666723874000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '2PvathWebooKLBrJpwPzdTrM1sLLiWHCrJ6TzSfh5Tkm',
      address: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q',
      signature: 'ZyeTceCitQ9xGgMktaJsB5kDzkrjuZTnHRcvcNxYsZYbjmPdnkw5wNYA6CwaTykSchD8dPSvdcryGaTCdaqxdb7'
    }
  ],
  contractId: 'CEu9aFoVwdApYBAPFy4hTYc2NUJRzoL5VYc',
  functionIndex: 0,
  functionData: '1bscuJD5pDLBReyZLKHWPXGEFkZxrBq2GaKRLX',
  attachment: '2aTZvrfa2Ax23REA3BKNRVqbgHBsmjYCHWoAj9npRRz'
}

Issue

Issue the a certain amount of the token. The issued tokens will belong to the issuer.

Note that only the address with the issuer role can take this action.

// acnt: Account
// tc: TokCtrtWithSplit

let data1 = await tc.issue(acnt1, 2500);

console.log(data1);

Example output

{
  type: 9,
  id: '9kbym8sBrNLrsBpBUccuUfZepv7VowrPUuVb72tDyBnj',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654666519468000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '2PvathWebooKLBrJpwPzdTrM1sLLiWHCrJ6TzSfh5Tkm',
      address: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q',
      signature: '2SBaQp4UnepYmpZagmQ25WAW1Yh7NVEq4UtgkFY7C3XijccRw3WJsWCKa4PW5JYLBfo3pPT9WuMRbEmiJGAVtoih'
    }
  ],
  contractId: 'CEu9aFoVwdApYBAPFy4hTYc2NUJRzoL5VYc',
  functionIndex: 1,
  functionData: '14JDCrdo1xyACX',
  attachment: ''
}

Send

Send a certain amount of the token to another user.

// acnt0: Account
// acnt1: Accout
// tc: TokCtrtWithSplit

let resp = await tc.send(
  acnt0, // by
  acnt1.addr.data, // recipient
  100 // amount
);
console.log(resp);

Example output

{
  type: 9,
  id: '381fZ8eeZ7SVKTnQfvU1P7HH3ewX3hQGPJFXBhzJRzgF',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654658766148000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '2PvathWebooKLBrJpwPzdTrM1sLLiWHCrJ6TzSfh5Tkm',
      address: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q',
      signature: '46jaDN6LwabEMijiQ6RWg2HL7pwswYWSyyaFmz7wCoFaRZmL4doHxC4EvMG2iafxJqXZD8PYDK2FTa7eMeQPSYFJ'
    }
  ],
  contractId: 'CEuFhD7N4sRfGnx6HZnCLnnd517Zgy19p4Q',
  functionIndex: 3,
  functionData: '14uNyP1vcvYHknSVFL8C4hVccNhDi737TxjF58tBNvpEcAcNGf1',
  attachment: 'YKYpT6ZcoWLMH2r6MBNvuoeLPFPCL8'
}

Destroy

Destroy a certain amount of the token.

Note that only the address with the issuer role can take this action.

// acnt: Accout
// tc: TokCtrtWithSplit

let resp = await tc.destroy(
  acnt, // by
  50 // amount
);
console.log(resp);

Example output

{
  type: 9,
  id: 'ECu4e6Rx5XRfjKFYVUdYBupb1SkaJXm2Nn9K3zhmDZh9',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654659488012000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '6VH5QC2ktUA5UK4j6c4hxQTZi4cm9jdNYhnCQV2rT4Wv',
      address: 'AU8xJNjE5RNo8hmPYA1bSgQzPKYNgejytiP',
      signature: '3QKcT6b3kKiwX1FCztXbWLRR288rD9UTqvCf4CpRHUToUpqbFzJwGeVPjyQanKDf6tJk9uPQQF5YwdPQ9sPWCh3t'
    }
  ],
  contractId: 'CEuFhD7N4sRfGnx6HZnCLnnd517Zgy19p4Q',
  functionIndex: 2,
  functionData: '14JDCrdo1xwuNP',
  attachment: '2Xnstj5JdDLk4UoJ7mAAN3CGaaFmKRvUfzGzN5x16v9'
}

Transfer

Transfer a certain amount of the token to another account(e.g. user or contract). transfer is the underlying action of send, deposit, and withdraw. It is not recommended to use transfer directly. Use send, deposit, withdraw instead when possible.

// acnt0: Accout
// acnt1: Accout
// tc: TokCtrtWithSplit

let resp = await tokB.transfer(
  acnt0, // by
  acnt0.addr.data, // sender
  acnt1.addr.data, // recipient
  10 // amount
);
console.log(resp);

Example output

{
  type: 9,
  id: 'EErHX4BNCzpfqk7fbrSed2XLKth9qRrPta37XzvsjvKL',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654659844659000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '6VH5QC2ktUA5UK4j6c4hxQTZi4cm9jdNYhnCQV2rT4Wv',
      address: 'AU8xJNjE5RNo8hmPYA1bSgQzPKYNgejytiP',
      signature: '26ZbVi2x8fMJrXfDf45ZsA2bcdS2iTacApeEwKwh4NaArgPTscEhZdL3vp4PLujkRMBmeXP84EYNSsn8qWffYeCY'
    }
  ],
  contractId: 'CEuFhD7N4sRfGnx6HZnCLnnd517Zgy19p4Q',
  functionIndex: 4,
  functionData: '14VJY1ZthR99KumZMvcjjGnwmMggYiBsTzkczYTL1fh62FGgJmJfWBJ1yGDjL7nEHzYr6iGDzhVwK4KCQnjDxurf',
  attachment: '26U7Yk1UsXAPPLDaRK4FPsoE'
}

Deposit

Deposit a certain amount of the token into a token-holding contract instance(e.g. lock contract).

Note that only the token defined in the token-holding contract instance can be deposited into it.

// acnt: Accout
// tc: TokCtrtWithSplit
// lc: LockCtrt

const lcId = lc.ctrtId.data;

let resp = await tc.deposit(
  acnt, // by
  lcId, // ctrtId
  100 // amount
);
console.log(resp);

Example output

{
  type: 9,
  id: 'B4xTs6aTvTSc4HA7TDPgSX5uNg9tBNhjaweBMVv3V66o',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654661416631000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '2PvathWebooKLBrJpwPzdTrM1sLLiWHCrJ6TzSfh5Tkm',
      address: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q',
      signature: '2X4YWHNUCB8eBEgVoSEMJhdWLWFodDpus4jZQPRWp8xqXmQx4XGthe7x3EETXomWdebp4EQ1fpMTgemkZAGtVrBq'
    }
  ],
  contractId: 'CEuFhD7N4sRfGnx6HZnCLnnd517Zgy19p4Q',
  functionIndex: 5,
  functionData: '14VJY124dSzeYQLb1TnhVGx2HCWyqimTHEh2dQw7g5z2zS1V6fQrpu9rhVQG4owL8ScRfD79ntBekaWPxoai8d4B',
  attachment: '2Xnskmww39TWaHYgpQjToZWq6CbWjbKQkv5YNyHtz8b'
}

Withdraw

Withdraw a certain amount of the token from a token-holding contract instance(e.g. lock contract).

Note that only the token defined in the token-holding contract instance can be withdrawn from it.

// acnt: Accout
// tc: TokCtrtWithSplit
// lc: LockCtrt

const lcId = lc.ctrtId.data;

let resp = await tc.withdraw(
  acnt, // by
  lcId, // ctrtId
  100 // amount
);
console.log(resp);

Example output

{
  type: 9,
  id: 'b1tNgLYRQLm5dMxrF2NSYnJzUH25oixw85snGqWGBiX',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654661447784000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '2PvathWebooKLBrJpwPzdTrM1sLLiWHCrJ6TzSfh5Tkm',
      address: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q',
      signature: 'pPQ7M4fUKcCpUvoyYK3BKLYGfvvWkvWpNRmXh5gKxzQ99PhBEM6cJTPFvPwftB1ffoTJSks5B58WxGoWWWbkMJd'
    }
  ],
  contractId: 'CEuFhD7N4sRfGnx6HZnCLnnd517Zgy19p4Q',
  functionIndex: 6,
  functionData: '14WMYf6g4W8vNhWqmQ8okgnviNcAbsY3xf1w8DypLquRJM6YYDkC8sgY4HakSZ3zCQJRT1x7GKYFRZMyhPt92e95',
  attachment: '2EEcDWCrw6nEYnXvVj4qkomcCf4eXDdUQV3pRuM'
}

Split

Update the unit of the token.

The address with the issuer & maker role can take this action.

// acnt: Accout
// tc: TokCtrtWithSplit

let resp = await tc.split(acnt, 1000, 'change unit');
console.log(resp);
console.log(await tc.getUnit());

Example output

{
  type: 9,
  id: 'Dy8aZxmVN24zKs48eiwxsHH5UmUybe9R4FBCKGrPkvrs',
  fee: 30000000,
  feeScale: 100,
  timestamp: 1654667764998000000,
  proofs: [
    {
      proofType: 'Curve25519',
      publicKey: '2PvathWebooKLBrJpwPzdTrM1sLLiWHCrJ6TzSfh5Tkm',
      address: 'ATracVxHwdYF394gXEawdZe9stB9yLH6V7q',
      signature: '5pvAVAkN1pjPzvbSxfdfYugH6jZ7aRLVkVzMDbz14o1GCanpsrtnGtgvuQ29sutzcqTnkYxnnHTRjTbVmvPACA9'
    }
  ],
  contractId: 'CEu9aFoVwdApYBAPFy4hTYc2NUJRzoL5VYc',
  functionIndex: 3,
  functionData: '14JDCrdo1xwstM',
  attachment: 'RejhgSP2U2YiFZ5'
}
1000