doc/index.md

   1 # Java SDK documentation
   2
   3 This page will document the API classes and ways to properly use the API.
   4 Subsequent new releases also maintain backward compatibility with this class approach.
   5
   6 ## Basic Usage
   7
   8 ```
   9 public static Client generateClient() throws BytomException {
  10     String coreURL = Configuration.getValue("bytom.api.url");
  11     String accessToken = Configuration.getValue("client.access.token");
  12     if (coreURL == null || coreURL.isEmpty()) {
  13         coreURL = "http://127.0.0.1:9888/";
  14     }
  15     return new Client(coreURL, accessToken);
  16 }
  17
  18 Client client = TestUtils.generateClient();
  19 ```
  20
  21 ## Usage
  22
  23 * [`Step 1: Create a key`](#create-a-key)
  24 * [`Step 2: Create an account`](#create-an-account)
  25 * [`Step 3: Create an receiver`](#create-an-receiver)
  26 * [`Step 4: Create an asset`](#create-an-asset)
  27 * [`Step 5: Issue asset`](#issue-asset)
  28     * [`Firstly build the transaction`](#firstly-build-the-transaction)
  29     * [`Secondly sign the transaction`](#secondly-sign-the-transaction)
  30     * [`Finally submit the transaction`](#finally-submit-the-transaction)
  31
  32 > For more details, see [`API methods`](#api-methods)
  33
  34 ## Create a key
  35
  36 ```java
  37 String alias = "test";
  38 String password = "123456";
  39
  40 Key.Builder builder = new Key.Builder().setAlias(alias).setPassword(password);
  41 Key key = Key.create(client, builder);
  42 ```
  43
  44 ## Create an account
  45
  46 ```java
  47 String alias = "sender-account";
  48 Integer quorum = 1;
  49 List<String> root_xpubs = new ArrayList<String>();
  50 root_xpubs.add(senderKey.xpub);
  51
  52 Account.Builder builder = new Account.Builder().setAlias(alias).setQuorum(quorum).setRootXpub(root_xpubs);
  53
  54 Account account = Account.create(client, builder);
  55 ```
  56
  57 ## Create an receiver
  58
  59 ```java
  60 String alias = receiverAccount.alias;
  61 String id = receiverAccount.id;
  62
  63 Account.ReceiverBuilder receiverBuilder = new Account.ReceiverBuilder().setAccountAlias(alias).setAccountId(id);
  64 Receiver receiver = receiverBuilder.create(client);
  65 ```
  66
  67 ## Create an asset
  68
  69 ```java
  70  String alias = "receiver-asset";
  71
  72 List<String> xpubs = receiverAccount.xpubs;
  73
  74 Asset.Builder builder = new Asset.Builder()
  75                         .setAlias(alias)
  76                         .setQuorum(1)
  77                         .setRootXpubs(xpubs);
  78 receiverAsset = builder.create(client);
  79 ```
  80
  81 ## Issue asset
  82
  83 ### Firstly build the transaction
  84
  85 ```java
  86 Transaction.Template controlAddress = new Transaction.Builder()
  87         .addAction(
  88                 new Transaction.Action.SpendFromAccount()
  89                         .setAccountId(senderAccount.id)
  90                         .setAssetId(senderAsset.id)
  91                         .setAmount(300000000)
  92         )
  93         .addAction(
  94                 new Transaction.Action.ControlWithAddress()
  95                         .setAddress(receiverAddress.address)
  96                         .setAssetId(senderAsset.id)
  97                         .setAmount(200000000)
  98         ).build(client);
  99 ```
 100
 101 ### Secondly sign the transaction
 102
 103 ```java
 104 Transaction.Template singer = new Transaction.SignerBuilder().sign(client,
 105         controlAddress, "123456");
 106 ```
 107
 108 ### Finally submit the transaction
 109
 110 ```java
 111 Transaction.SubmitResponse txs = Transaction.submit(client, singer);
 112 ```
 113
 114 ----
 115
 116 ## API methods
 117
 118 * [`Key API`](#key-api)
 119 * [`Account API`](#account-api)
 120 * [`Asset API`](#asset-api)
 121 * [`Transaction API`](#transaction-api)
 122 * [`Wallet API`](#wallet-api)
 123 * [`Access Token API`](#access-token-api)
 124 * [`Block API`](#block-api)
 125 * [`Other API`](#other-api)
 126
 127 ## Key API
 128
 129
 130 #### createKey
 131
 132 ```java
 133 Key create(Client client, Builder builder);
 134 ```
 135
 136 ##### Parameters
 137
 138 - `Client` - *client*, Client object that makes requests to the core.
 139 - `Key.Builder` - *builder*, Builder object that builds request parameters.
 140
 141 ##### Returns
 142
 143 - `Key` - *key*, Key object.
 144
 145 ----
 146
 147 #### listKeys
 148
 149 ```java
 150 List<Key> list(Client client);
 151 ```
 152
 153 ##### Parameters
 154
 155 - `Client` - *client*, Client object that makes requests to the core.
 156
 157 ##### Returns
 158
 159 - `List of Key`, *List<Key>*, an ArrayList object contains Key objects.
 160
 161 ----
 162
 163 #### deleteKey
 164
 165 ```java
 166 void delete(Client client, String xpub, String password);
 167 ```
 168
 169 ##### Parameters
 170
 171 - `Client` - *client*, Client object that makes requests to the core.
 172 - `String` - *xpub*, pubkey of the key.
 173 - `String` - *password*, password of the key.
 174
 175 ##### Returns
 176
 177 none if the key is deleted successfully.
 178
 179 ----
 180
 181 #### resetKeyPassword
 182
 183 ```java
 184 void resetPwd(Client client, String xpub, String oldPwd, String newPwd);
 185 ```
 186
 187 ##### Parameters
 188
 189 - `Client` - *client*, Client object that makes requests to the core.
 190 - `String` - *xpub*, pubkey of the key.
 191 - `String` - *oldPwd*, old password of the key.
 192 - `String` - *newPwd*, new password of the key.
 193
 194 ##### Returns
 195
 196 none if the key password is reset successfully.
 197
 198
 199 ## Account API
 200
 201
 202 #### createAccount
 203
 204 ```java
 205 Account create(Client client, Builder builder);
 206 ```
 207 ##### Parameters
 208
 209 - `Client` - *client*, Client object that makes requests to the core.
 210 - `Account.Builder` - *builder*, Builder object that builds request parameters.
 211
 212 ##### Returns
 213
 214 - `Account` - *account*, Account object.
 215
 216 ----
 217
 218 #### listAccounts
 219
 220 ```java
 221 List<Account> list(Client client);
 222 ```
 223
 224 ##### Parameters
 225
 226 - `Client` - *client*, Client object that makes requests to the core.
 227
 228 ##### Returns
 229
 230 - `List of Account`, *List<Account>*, an ArrayList object contains Account objects.
 231
 232 ----
 233
 234 #### deleteAccount
 235
 236 ```java
 237 void delete(Client client, String account_info);
 238 ```
 239
 240 ##### Parameters
 241
 242 - `Client` - *client*, Client object that makes requests to the core.
 243 - `String` - *account_info*, alias or ID of account.
 244
 245 ##### Returns
 246
 247 none if the account is deleted successfully.
 248
 249 ----
 250
 251 #### createAccountReceiver
 252
 253 ```java
 254 Receiver create(Client client);
 255 ```
 256
 257 ##### Parameters
 258
 259 - `Client` - *client*, Client object that makes requests to the core.
 260
 261 ##### Returns
 262
 263 - `Receiver` - *receiver*, Receiver object.
 264
 265
 266 ----
 267
 268 #### listAddresses
 269
 270 ```java
 271 List<Address> list(Client client);
 272 ```
 273
 274 ##### Parameters
 275
 276 - `Client` - *client*, Client object that makes requests to the core.
 277
 278 ##### Returns
 279
 280 - `List of Address`, *List<Address>*, an ArrayList object contains Address objects.
 281
 282 ----
 283
 284 #### validateAddress
 285
 286 ```java
 287 Address validate(Client client, String address);
 288 ```
 289
 290 ##### Parameters
 291
 292 - `Client` - *Client*, Client object that makes requests to the core.
 293 - `String` - *address*, address of account.
 294
 295 ##### Returns
 296
 297 - `Address` - *address*, an Address object.
 298
 299
 300 ## Asset API
 301
 302
 303 #### createAsset
 304
 305 ```java
 306 Asset create(Client client);
 307 ```
 308
 309 ##### Parameters
 310
 311 - `Client` - *Client*, Client object that makes requests to the core.
 312
 313 ##### Returns
 314
 315 - `Asset` - *asset*, an Asset object.
 316
 317 ----
 318
 319 #### getAsset
 320
 321 ```java
 322 Asset get(Client client);
 323 ```
 324
 325 ##### Parameters
 326
 327 - `Client` - *Client*, Client object that makes requests to the core.
 328
 329 ##### Returns
 330
 331 - `Asset` - *asset*, an Asset object.
 332
 333 ----
 334
 335 #### listAssets
 336
 337 ```java
 338 List<Asset> list(Client client);
 339 ```
 340
 341 ##### Parameters
 342
 343 - `Client` - *Client*, Client object that makes requests to the core.
 344
 345 ##### Returns
 346
 347 - `List of Asset`, *List<Asset>*, an ArrayList object contains Asset objects.
 348
 349 ----
 350
 351 #### updateAssetAlias
 352
 353 ```java
 354 void update(Client client);
 355 ```
 356
 357 ##### Parameters
 358
 359 - `Client` - *Client*, Client object that makes requests to the core.
 360
 361 ##### Returns
 362
 363 none if the asset alias is updated success.
 364
 365 ----
 366
 367 #### listBalances
 368
 369 ```java
 370 List<Balance> list(Client client);
 371 ```
 372
 373 ##### Parameters
 374
 375 - `Client` - *Client*, Client object that makes requests to the core.
 376
 377 ##### Returns
 378
 379 - `List of Balance`, an ArrayList object contains Balance objects.
 380
 381 ----
 382
 383 #### listUnspentOutPuts
 384
 385 ```java
 386 List<UnspentOutput> list(Client client);
 387 ```
 388
 389 ##### Parameters
 390
 391 - `Client` - *Client*, Client object that makes requests to the core.
 392
 393 ##### Returns
 394
 395 - `List of UnspentOutput`, an ArrayList object contains UnspentOutput objects.
 396
 397
 398 ## Transaction API
 399
 400
 401 #### buildTransaction
 402
 403 ```java
 404 Template build(Client client);
 405 ```
 406
 407 ##### Parameters
 408
 409 - `Client` - *Client*, Client object that makes requests to the core.
 410
 411 ##### Returns
 412
 413 - `Template` - *template*, a template object.
 414
 415 ----
 416
 417 #### signTransaction
 418
 419 ```java
 420 Template sign(Client client, Template template, String password);
 421 ```
 422
 423 ##### Parameters
 424
 425 `Object`:
 426
 427 - `Client` - *Client*, Client object that makes requests to the core.
 428 - `Template` - *template*, a template object.
 429 - `String` - *password*, signature of the password.
 430
 431 ##### Returns
 432
 433 - `Template` - *template*, a template object.
 434
 435 ----
 436
 437 #### submitTransaction
 438
 439 ```java
 440 SubmitResponse submit(Client client, Template template);
 441 ```
 442
 443 ##### Parameters
 444
 445 - `Client` - *Client*, Client object that makes requests to the core.
 446 - `Template` - *template*, a template object.
 447
 448 ##### Returns
 449
 450 - `SubmitResponse` - *submitResponse*, a SubmitResponse object
 451
 452 ----
 453
 454 #### estimateTransactionGas
 455
 456 ```java
 457 TransactionGas estimateGas(Client client, Template template);
 458 ```
 459
 460 ##### Parameters
 461
 462 - `Client` - *Client*, Client object that makes requests to the core.
 463 - `Template` - *template*, a template object.
 464
 465 ##### Returns
 466
 467 - `TransactionGas` - *transactionGas*, a TransactionGas object
 468
 469 ----
 470
 471 #### getTransaction
 472
 473 ```java
 474 Transaction get(Client client);
 475 ```
 476
 477 ##### Parameters
 478
 479 - `Client` - *Client*, Client object that makes requests to the core.
 480
 481 ##### Returns
 482
 483 - `Transaction` - *transaction*, a Transaction object
 484
 485 ----
 486
 487 #### listTransactions
 488
 489 ```java
 490 List<Transaction> list(Client client);
 491 ```
 492
 493 ##### Parameters
 494
 495 - `Client` - *Client*, Client object that makes requests to the core.
 496
 497 ##### Returns
 498
 499 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 500
 501 ##### Example
 502
 503 ```java
 504 //list all transactions
 505 List<Transaction> transactionList = new Transaction.QueryBuilder().list(client);
 506 ```
 507
 508 ----
 509
 510 #### listTransactionsById
 511
 512 ```java
 513 List<Transaction> listById(Client client);
 514 ```
 515
 516 ##### Parameters
 517
 518 - `Client` - *Client*, Client object that makes requests to the core.
 519
 520 ##### Returns
 521
 522 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 523
 524 ##### Example
 525
 526 ```java
 527 String tx_id = "f04d4d9b2580ff6496f9f08d903de5a2365975fb8d65b66ca4259f152c5dd134";
 528 //list all transactions by tx_id
 529 List<Transaction> transactionList = new Transaction.QueryBuilder().setTxId(tx_id).list(client);
 530 ```
 531
 532 ----
 533
 534 #### listTransactionsByAccountId
 535
 536 ```java
 537 List<Transaction> listByAccountId(Client client);
 538 ```
 539
 540 ##### Parameters
 541
 542 - `Client` - *Client*, Client object that makes requests to the core.
 543
 544 ##### Returns
 545
 546 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 547
 548 ##### Example
 549
 550 ```java
 551 String account_id = "0E6KP8C100A02";
 552 //list all transactions by account_id
 553 List<Transaction> transactionList = new Transaction.QueryBuilder().setAccountId(account_id).list(client);
 554 ```
 555
 556 ## Wallet API
 557
 558
 559 #### backupWallet
 560
 561 ```java
 562 Wallet backupWallet(Client client);
 563 ```
 564
 565 ##### Parameters
 566
 567 - `Client` - *Client*, Client object that makes requests to the core.
 568
 569 ##### Returns
 570
 571 - `Wallet` - *wallet*, a Wallet object
 572
 573 ----
 574
 575 #### restoreWallet
 576
 577 ```java
 578 void restoreWallet(Client client ,Object accountImage, Object assetImage , Object keyImages);
 579 ```
 580
 581 ##### Parameters
 582
 583 `Object`:
 584 - `Client` - *Client*, Client object that makes requests to the core.
 585 - `Object` - *account_image*, account image.
 586 - `Object` - *asset_image*, asset image.
 587 - `Object` - *key_images*, key image.
 588
 589 ##### Returns
 590
 591 none if restore wallet success.
 592
 593
 594 ## Access Token API
 595
 596 ```java
 597 //example
 598 AccessToken accessToken = new AccessToken.Builder().setId("sheng").create(client);
 599
 600 List<AccessToken> tokenList = AccessToken.list(client);
 601
 602 String secret = "5e37378eb59de6b10e60f2247ebf71c4955002e75e0cd31ede3bf48813a0a799";
 603 AccessToken.check(client, "sheng", secret);
 604 ```
 605
 606 #### createAccessToken
 607
 608 ```java
 609 AccessToken create(Client client);
 610 ```
 611
 612 ##### Parameters
 613
 614 - `Client` - *Client*, Client object that makes requests to the core.
 615
 616 ##### Returns
 617
 618 - `AccessToken` - *accessToken*, an AccessToken object.
 619
 620 ----
 621
 622 #### listAccessTokens
 623
 624 ```java
 625 List<AccessToken> list(Client client);
 626 ```
 627
 628 ##### Parameters
 629
 630 - `Client` - *Client*, Client object that makes requests to the core.
 631
 632 ##### Returns
 633
 634 - `Array of Object`, access token array.
 635
 636 ----
 637
 638 #### deleteAccessToken
 639
 640 ```java
 641 void delete(Client client, String id);
 642 ```
 643
 644 ##### Parameters
 645
 646 - `Client` - *Client*, Client object that makes requests to the core.
 647 - `String` - *id*, token ID.
 648
 649 ##### Returns
 650
 651 none if the access token is deleted successfully.
 652
 653 ----
 654
 655 #### checkAccessToken
 656
 657 ```java
 658 void check(Client client, String id, String secret);
 659 ```
 660
 661 ##### Parameters
 662
 663 - `Client` - *Client*, Client object that makes requests to the core.
 664 - `String` - *id*, token ID.
 665 - `String` - *secret*, secret of token, the second part of the colon division for token.
 666
 667 ##### Returns
 668
 669 none if the access token is checked valid.
 670
 671
 672 ## Block API
 673
 674
 675 #### getBlockCount
 676
 677 ```java
 678 Integer getBlockCount(Client client);
 679 ```
 680
 681 ##### Parameters
 682
 683 none
 684
 685 ##### Returns
 686
 687 - `Integer` - *block_count*, recent block height of the blockchain.
 688
 689 ----
 690
 691 #### getBlockHash
 692
 693 ```java
 694 String getBlockHash(Client client);
 695 ```
 696
 697 ##### Parameters
 698
 699 none
 700
 701 ##### Returns
 702
 703 - `String` - *block_hash*, recent block hash of the blockchain.
 704
 705 ----
 706
 707 #### getBlock
 708 ```php
 709 Block getBlock(Client client);
 710 ```
 711
 712 ##### Parameters
 713
 714 - `Client` - *Client*, Client object that makes requests to the core.
 715
 716 ##### Returns
 717
 718 - `Block` - *block*, a Block object.
 719
 720 ----
 721
 722 #### getBlockHeader
 723
 724 ```java
 725 BlockHeader getBlockHeader(Client client);
 726 ```
 727
 728 ##### Parameters
 729
 730 - `Client` - *Client*, Client object that makes requests to the core.
 731
 732 ##### Returns
 733
 734 - `BlockHeader` - *blockHeader*, header of block.
 735
 736 ----
 737
 738 #### getDifficulty
 739
 740 ```java
 741 BlockDifficulty getBlockDifficulty(Client client);
 742 ```
 743
 744 ##### Parameters
 745
 746 - `Client` - *Client*, Client object that makes requests to the core.
 747
 748 ##### Returns
 749
 750 - `BlockDifficulty` - *blockDifficulty*, a BlockDifficulty object
 751
 752 ----
 753
 754 #### getHashRate
 755
 756 ```java
 757 BlockHashRate getHashRate(Client client);
 758 ```
 759
 760 ##### Parameters
 761
 762 - `Client` - *Client*, Client object that makes requests to the core.
 763
 764 ##### Returns
 765
 766 - `BlockHashRate` - *blockHashRate*, a BlockHashRate object
 767
 768
 769 ## Other API
 770
 771
 772 #### netInfo
 773
 774 ```java
 775 NetInfo getNetInfo(Client client);
 776 ```
 777
 778 ##### Parameters
 779
 780 - `Client` - *Client*, Client object that makes requests to the core.
 781
 782 ##### Returns
 783
 784 - `NetInfo` - *netInfo*, a NetInfo object.
 785
 786 ----
 787
 788 #### gasRate
 789
 790 ```java
 791 Gas gasRate(Client client);
 792 ```
 793
 794 ##### Parameters
 795
 796 - `Client` - *Client*, Client object that makes requests to the core.
 797
 798 ##### Returns
 799
 800 - `Gas` - *gas*, a Gas object.
 801
 802 ----
 803
 804 #### verifyMessage
 805
 806 ```java
 807 Boolean verifyMessage(Client client);
 808 ```
 809
 810 ##### Parameters
 811
 812 - `Client` - *Client*, Client object that makes requests to the core.
 813
 814 ##### Returns
 815
 816 - `Boolean` - *result*, verify result.
 817