Documents

Usage for jcc_jingtum_lib

Server

Server class connects jingtum with ws lib to keep long connection. It's packaged to Remote class, should not be used outside jcc_jingtum_lib.

Remote

Main function class in jcc_jingtum_lib. It creates a handle with jingtum, makes request to jingtum, subscribes event to jingtum, ands gets info from jingtum.

Remote(options)
connect(callback)
disconnect()
requestServerInfo()
requestLedgerClosed()
requestLedger(options)
requestTx(options)
requestAccountInfo(options)
requestAccountTums(options)
requestAccountRelations(options)
requestAccountOffers(options)
requestAccountTx(options)
requestOrderBook(options)
requestPathFind(options)
createAccountStub()
createOrderBookStub()
buildPaymentTx(options)
buildRelationTx(options)
buildAccountSetTx(options)
buildOfferCreateTx(options)
buildOfferCancelTx(options)

Remote(options)

options for setup a remote, options including

{
  "server": "wss://ts.jingtum.com:5020",
  "token": "swt",
  "local_sign": false
}

server is string for jingtum websocket server url, local_sign checks if jcc_jingtum_lib sign transaction in local, token is string for jingtum or jingtum alliance chains, the value is swt or bwt that respectively represents jingtum chain and bizain chain.

bwt是商链的原生币，也是燃料币，商链是井通链的联盟链，如果添加新的联盟链，需要在 jcc_jingtum_base_lib项目中src/wallet_config.js 添加新的联盟链定义即可，如果需要我们增加请联系我们。

BWT is the native token and gas token of BIZAIN. BIZAIN is the alliance chain of jingtum. If you add a new alliance chain, you need to add a new definition of the alliance chain in project jcc_jingtum_base_lib folder src/wallet_config.js.

If you need to add it in this package, please contact us.

connect(callback)

Each remote object should connect jingtum first. Now jingtum should connect manual, only then you can send request to backend. callback as callback(err, ret), err checks error info, ret is restul result.

disconnect

Remote object can be disconnected manual, and no parameters are required.

requestServerInfo

Create request object and get server info from jingtum, including

{
  "version": "0.29.60", //服务程序版本号
  "ledgers": "6753-14393", //该服务缓存的账本区间
  "node": "n9LxdTZbjjQnuPiM5SgwPYQndfb64YHbmCp1mhsoch7uw5HQJ3k6", //节点公钥
  "state": "full   34:35:40" //服务器当前状态：full可提供服务状态；proposing验证节点状态
}

version is currenct jingtum version; ledgers are complted ledgers in system; node is jingtum node id; state is currenct jingtum node state.

requestLedgerClosed

Create request object and get last closed ledger in system. return data include ledger_index, ledger_hash and so on.

{
  "fee_base": 10,
  "ledger_hash": "326EF17272606D8DD72F96F6299E54839D76435DCEB6F68385D891105ABB0E6C",
  "ledger_index": 14402,
  "reserve_base": 10000000,
  "reserve_inc": 1000000,
  "txn_count": 0,
  "validated": "6753-14402"
}

fee_base is current swt fee in each transaction. ledger_hash and ledger_index are last closed ledger height info. reserve_base and reserve_inc are reserve swt infomations. txn_count is transaction count in last closed ledger. validated is current validated ledgers in last cloed ledger.

requestLedger(options)

options can be ledger index and ledger hash. If none is provided, then last closed ledger is returned.

{
  "accepted": true,
  "ledger_hash": "32A1E3E58000183D5D50E9662133183DFA9BA695763B4D44B5FEDF71476A1DF1",
  "ledger_index": "14468",
  "parent_hash": "6CEBA5BC7EDDD3AD110F5F9933FE2301443A99BC7158DFF19C04AF5E7F5BABD3",
  "close_time": "2016-Nov-26 14:43:10",
  "total_coins": "600000000000000000"
}

accepted marks the ledger is accepted. ledger_hash and ledger_index are ledger height informations. parent_hash is parent ledger hash. close_time is ledger closed time in UTC+8. total_coins is total swt in system.

requestTx(options)

requestTx is used to query one transaction information. Options should be proivide transaction hash as

{
  "hash": "6E7F4962B3B13E3D9C0D13120E17FE1B3DBF4EA677D1D19AAEC38C9B74EBF73B"
}

Each result is one transaction information. The result is as follow

{
  "Account": "jhYk8VyFaHYwQRgqNfrP9QcPkRmJoEFB6V",
  "Fee": "12",
  "Flags": 2148007936,
  "LastLedgerSequence": 4518373,
  "Sequence": 3,
  "SigningPubKey": "029E5D69804957211EB45BF973CDCCD994466BA672C997808892F657DE41A4CB1B",
  "TakerGets": "1000000",
  "TakerPays": {
    "currency": "CNY",
    "issuer": "jBciDE8Q3uJjf111VeiUNM775AMKHEbBLS",
    "value": "0.9499999999"
  },
  "TransactionType": "OfferCreate",
  "TxnSignature": "30440220729E10A9A5F60DE4839E8284E0532BA5741539AACFD3598922102A7FD48E96C60220588921DE0F892241F863D0BB2436D55E15C4D7259A874A9023ACC8814C4D4B9C",
  "date": 533033560,
  "hash": "D2B8DBDBC4D8264DAE461A24CCA9AD790DEB10F091F5528DB97D3A74AE6C75C6",
  "inLedger": 4518365,
  "ledger_index": 4518365,
  "meta": {
    "AffectedNodes": [{
      "ModifiedNode": {
        "FinalFields": {
          "Account": "j9eM8GiBb4QFRZZsrsde6XTPDenXEFnrkm",
          "Balance": "13371029608006",
          "Flags": 0,
          "OwnerCount": 9,
          "Sequence": 12
        },
        "LedgerEntryType": "AccountRoot",
        "LedgerIndex": "9A70EC2B21AC5C85498444281EABF08CF63BB8844B407300B385371A0623F0D7",
        "PreviousFields": {
          "Balance": "13371028608006"
        },
        "PreviousTxnID": "BBE8F8CFB2CA6EFA10C1884EFFD36154B30702D9446D10A6158106D168B65C83",
          "PreviousTxnLgrSeq" : 4465533
        }
    }],
    "TransactionIndex": 0,
    "TransactionResult": "tesSUCCESS"
  },
  "status": "success",
  "validated": true
}

requestAccountInfo(options)

It is used to get account info. Options should provie account, and ledger is optional. Options are as follow.

{
  "account": "jLiQ4FfNhezwFzQEgKAKNHBM35S2BnJwxj",
  "ledger_index": "10000"
}

And result is as follow

{
  "account_data": {
    "Account": "jLiQ4FfNhezwFzQEgKAKNHBM35S2BnJwxj",
    "Balance": "1001999904",
    "Flags": 0,
    "LedgerEntryType": "AccountRoot",
    "OwnerCount": 5,
    "PreviousTxnID": "F39560463022FD9ED78BA378DB2D2DD6CC46ECCA5F2D5A052916BE22C1A1B845",
    "PreviousTxnLgrSeq": 8173,
    "Sequence": 9,
    "index": "7B12CC6E0B76FC0CA1CD11436488C1CE3C1709B93EF62CD9E6155C3A9D7554A0"
  },
  "ledger_hash": "F0F8799C2F7DCD3DE3F429831640F4520C1BAF5F55E505A9925DBF6B0C8D12E4",
  "ledger_index": 14531,
  "validated": true
}

account_data is account data information. ledger_index and ledger_hash is ledger height for the account.

requestAccountTums(options)

Each account helds many jingtum tums, and the received and sent tums can be found by requestAccountTums. The Options are as follow

{
  "account": "jLiQ4FfNhezwFzQEgKAKNHBM35S2BnJwxj",
  "ledger_index": "10000"
}

account parameter is required and ledger_inex or ledger_hash or ledger are optional.

The result is as follow

{
  "ledger_hash": "084769A988AFF8B430E71D1F9E6FBC1452C8DE06A84405BF6B5EE49D0B30ED6B",
  "ledger_index": 14559,
  "receive_currencies": ["CNY", "EUR", "USD"],
  "send_currencies": ["CNY"],
  "validated": true
}

receive_currencies is tums that can be received by this account, send_currenies is tums that will be sent by this account.

requestAccountRelations(options)

Jingtum wallet is connected by many relations. Now jingtum support trust, authorize and freeze relation, all can be query by requestAccountRelations. The query options is as follow

{
  "type": "trust",
  "account": "jLiQ4FfNhezwFzQEgKAKNHBM35S2BnJwxj",
  "ledger_index": "10000"
}

The result is as follow

{
  "account": "jLiQ4FfNhezwFzQEgKAKNHBM35S2BnJwxj",
  "ledger_hash": "1565BD1869E0CE4E23B78DE09BA624E39E79E1DDDF22A0979881C1D3D937E391",
  "ledger_index": 14604,
  "lines": [{
    "account": "jBciDE8Q3uJjf111VeiUNM775AMKHEbBLS",
    "balance": "0",
    "currency": "USD",
    "limit": "1000",
    "limit_peer": "0",
    "no_skywell": true,
    "quality_in": 0,
    "quality_out": 0
  }, {
    "account": "jBciDE8Q3uJjf111VeiUNM775AMKHEbBLS",
    "balance": "29997.5",
    "currency": "CNY",
    "limit": "10000000000",
    "limit_peer": "0",
    "no_skywell": true,
    "quality_in": 0,
    "quality_out": 0
  }, {
    "account": "j6wtnp1LB23h4hRQjk2tA3hCzNMnRW1j3",
    "balance": "0",
    "currency": "USD",
    "limit": "1000",
    "limit_peer": "0",
    "no_skywell": true,
    "quality_in": 0,
    "quality_out": 0
  }, {
    "account": "jBciDE8Q3uJjf111VeiUNM775AMKHEbBLS",
    "balance": "0",
    "currency": "EUR",
    "limit": "1000",
    "limit_peer": "0",
    "no_skywell": true,
    "quality_in": 0,
    "quality_out": 0
  }],
  "validated": true
}

requestAccountOffers(options)

requestAccountOffers query account's current offer that is suspended on jingtum system, and will be filled by other accounts. Options is the same as requestAccountInfo and requestAccountTums. And The request is as follow.

{
  "account": "jLiQ4FfNhezwFzQEgKAKNHBM35S2BnJwxj",
  "ledger_hash": "CB3F1AE7904E1F4676F8041848C1866280074C3D705D51C2ABC0FCB13C61ED9F",
  "ledger_index": 14630,
  "offers": [{
    "flags": 131072,
    "seq": 3,
    "taker_gets": "2000000",
    "taker_pays": {
      "value": "0.01",
      "currency": "USD",
      "issuer": "jBciDE8Q3uJjf111VeiUNM775AMKHEbBLS"
    }
  }],
  "validated": true
}

requestAccountTx(options)

It is used to query account transactions, and the options is same as requestAccountInfo. The request is as array of transaction.

requestOrderBook(options)

requestOrderBook is used to query order book info. The options is as follow.

{
  "gets": {
    "currency": "CNY",
    "issuer": "jBciDE8Q3uJjf111VeiUNM775AMKHEbBLS"
  },
  "pays": {
    "currency": "SWT",
    "issuer": ""
  }
}

Firstly , each order book has a currency pair, as AAA/BBB. When to quer the bid orders, gets is AAA and pays is BBB. When to query the ask orders, gets is BBB and pays is AAA. The result is array of orders.

requestPathFind(options)

It is used to query path from one curreny to another. Options is as follow.

{
  "account": "jpidrAsPWDTTHhbBf9BCn5suWHQJqhynVi",
  "destination": "jEo4AY8MFitgyRTNwnQCwSesn1XWjbY9Aa",
  "amount": {
    "value": "0.001",
    "currency": "SWT",
    "issuer": ""
  }
}

And the result is as follow.

[{
  "choice": {
    "currency": "BTC",
    "issuer": "jpidrAsPWDTTHhbBf9BCn5suWHQJqhynVi",
    "value": "0.001"
  },
  "key": "415aebe163e891e0f5cd63b328dbf0fee2fd51e8"
}, {
  "choice": {
    "currency": "USD",
    "issuer": "jpidrAsPWDTTHhbBf9BCn5suWHQJqhynVi",
    "value": "0.001"
  },
  "key": "f53b09afcf9e1758a7b647f2f738c86426cabfc1"
}]

In this path find, the user want to send swt to another account. The system provides two choices, one is to use BTC and the other is to use USD.

In each choice, one key is presented. Key is used to setPath in transaction parameter setting.

createAccountStub()

AcccountStub is account class, and is used to subscribe events of account. Each account is a event, and can be subscribed on account stub.

createOrderBookStub()

OrderBookStub is same as AccountStub. The event for OrderBookStub is orderbook currency pair, as AAA:issuer/BBB:issuer, and if AAA or BBB is SWT the part is SWT and no issuer is required.

buildPaymentTx(options)

Normal payment transaction. More parameters can be set by transaction functions. The secret is requried, and others are optional.

One options is as follow

{
  "from": "jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD",
  "to": "j9bouxUJLqw5QmtXWTarX7MpL8ohLJ57tJ",
  "amount": {
    "value": "1110.01",
    "currency": "SWT",
    "issuer": ""
  }
}

buildRelationTx(options)

Relation Transaction is built by this function. Now Jingtum supports trust, authorize and freeze relation setting. Same as payment transaction parameter setting, secret is required and others are optional.

One options is as follow

{
  "type": "trust",
  "account": "jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD",
  "limit": {
    "value": "10000",
    "currency": "CNY",
    "issuer": "jBciDE8Q3uJjf111VeiUNM775AMKHEbBLS"
  }
}

type is required to separate relation types.

buildAccountSetTx(options)

AccountSet Transaction is used to set account attribute. Now Jingtum supoorts three account attributes setting, as property, delegate and signer. property is used to set normal account info, delegate is used to set delegate account for this account, and signer is used to set signers for this acccount.

Same as payment transaction parameter setting, secret is required and others are optional.

One options is as follow

{
  "type": "delegate",
  "source": "jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD",
  "delegate_key": "j9zm131bYDNqaeZQvkRxwyLx3VD69KgmGi"
}

type is required to separate account setting types.

buildOfferCreateTx(options)

Create one offer and submit to system.

One options is as follow

{
  "source": "jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD",
  "type": "Sell",
  "gets": {
    "value": "1",
    "currency": "USD",
    "issuer": "jHVgw3zejmLbKaGEsM6go2HRXffWE9AJr4"
  },
  "pays": {
    "value": "1",
    "currency": "SWT",
    "issuer": ""
  }
}

type can be Sell or Buy, and is required. gets is the amount to get, pays is the amount can to exchange out.

buildOfferCancelTx(optoins)

Order can be cancel by order sequence. The sequence can be get when order is submitted or from offer query operation.

One options is as follow

{
  "source": "jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD",
  "sequence": 16
}

sequence is number and is requred.

Events

transactions

Listening all transactions occur in the system.

ledger_closed

Listening all last closed ledger event.

server_status

Listening all server status change event.

Request

Request is used to get server, account, orderbook and path info. Request is not secret required, and will be public to every one. All request is asynchronized and should provide a callback. Each callback has two parameter, one is error and the other is result.

selectLedger(ledger)
submit(callback)

selectLedger(ledger)

select one ledger for current request, ledger can be follow options,

ledger index
ledger hash
current, validated, closed

After ledger is selected, the result is for the specified ledger.

submit(callback)

Callback entry for request. Each callback has two parameter, one is error and the other is result.

Transaction

Transaction is used to make transaction and collect transaction parameter. Each transaction is secret required, and transaction can be signed local or remote. Now remote sign is supported, local sign will be suport soon. All transaction is asynchronized and should provide a callback. Each callback has two parameter, one is error and the other is result.

getAccount()
getTransactionType()
setSecret(secret)
addMemo(memo)
setPath(key)
setSendMax(amount)
setTransferRate(rate)
setFlags(flags)
submit(callback)

getAccount()

Each transaction has account, source, or from account, and its secret should be set.

Account can be master account, delegate account or operation account.

getTransactionType()

Get transaction type. Now Jingtum supports Payment, OfferCreate, OfferCancel, AccountSet and so on.

GetTransactionType return transaction type string.

setSecret(secret)

Set Transaction secret, this function is required before transaction submit.

addMemo(memo)

Add one memo to transaction, memo is string and is limited to 2k. Memo is one way to add payload to transaction. But payload should be add in another way.

setPath(key)

Set path for one transaction. The key parameter is request by requestPathFind. When the key is set, SendMax parameter is also set.

setSendMax(amount)

Set payment transaction max amount when needed. It is set by setPath default.

setTransferRate(rate)

Set transaction transfer rate. It should be check with fee.

TO CHECK

setFlags(flags)

Set transaction flags. It is used to set Offer type mainly. As follows

setFlags('Sell')

submit(callback)

Submit entry for transaction.

Account

Account is account stub for account events. One Account stub can subscribe many account events. Each event name is account address.

on('account')

Subscribe account event.

un('account')

Unsubscribe account event.

OrderBook

OrderBook is order book stub for order book events. One OrderBook stub can subscribe many order book events.

Each event name is order book pair. As follows

SWT:CNY/jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD

or

CNY/jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD:USD/jPgsnN1uRTiqiNsJinqDdshBaasHWzM4wD

on('orderbook')

Subscribe orderbook event.

un('orderbook')

Unsubscribe orderbook event.

Files

docs.md

Latest commit

History

docs.md

File metadata and controls

Documents

Server

Remote

Remote(options)

connect(callback)

disconnect

requestServerInfo

requestLedgerClosed

requestLedger(options)

requestTx(options)

requestAccountInfo(options)

requestAccountTums(options)

requestAccountRelations(options)

requestAccountOffers(options)

requestAccountTx(options)

requestOrderBook(options)

requestPathFind(options)

createAccountStub()

createOrderBookStub()

buildPaymentTx(options)

buildRelationTx(options)

buildAccountSetTx(options)

buildOfferCreateTx(options)

buildOfferCancelTx(optoins)

Events

transactions

ledger_closed

server_status

Request

selectLedger(ledger)

submit(callback)

Transaction

getAccount()

getTransactionType()

setSecret(secret)

addMemo(memo)

setPath(key)

setSendMax(amount)

setTransferRate(rate)

setFlags(flags)

submit(callback)

Account

on('account')

un('account')

OrderBook

on('orderbook')

un('orderbook')