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 * [`Mining API`](#mining-api)
 126 * [`Other API`](#other-api)
 127
 128 ## Key API
 129
 130
 131 #### createKey
 132
 133 ```java
 134 Key create(Client client, Builder builder);
 135 ```
 136
 137 ##### Parameters
 138
 139 - `Client` - *client*, Client object that makes requests to the core.
 140 - `Key.Builder` - *builder*, Builder object that builds request parameters.
 141
 142 ##### Returns
 143
 144 - `Key` - *key*, Key object.
 145
 146 ----
 147
 148 #### listKeys
 149
 150 ```java
 151 List<Key> list(Client client);
 152 ```
 153
 154 ##### Parameters
 155
 156 - `Client` - *client*, Client object that makes requests to the core.
 157
 158 ##### Returns
 159
 160 - `List of Key`, *List<Key>*, an ArrayList object contains Key objects.
 161
 162 ----
 163
 164 #### deleteKey
 165
 166 ```java
 167 void delete(Client client, String xpub, String password);
 168 ```
 169
 170 ##### Parameters
 171
 172 - `Client` - *client*, Client object that makes requests to the core.
 173 - `String` - *xpub*, pubkey of the key.
 174 - `String` - *password*, password of the key.
 175
 176 ##### Returns
 177
 178 none if the key is deleted successfully.
 179
 180 ----
 181
 182 #### resetKeyPassword
 183
 184 ```java
 185 void resetPwd(Client client, String xpub, String oldPwd, String newPwd);
 186 ```
 187
 188 ##### Parameters
 189
 190 - `Client` - *client*, Client object that makes requests to the core.
 191 - `String` - *xpub*, pubkey of the key.
 192 - `String` - *oldPwd*, old password of the key.
 193 - `String` - *newPwd*, new password of the key.
 194
 195 ##### Returns
 196
 197 none if the key password is reset successfully.
 198
 199
 200 ## Account API
 201
 202
 203 #### createAccount
 204
 205 ```java
 206 Account create(Client client, Builder builder);
 207 ```
 208 ##### Parameters
 209
 210 - `Client` - *client*, Client object that makes requests to the core.
 211 - `Account.Builder` - *builder*, Builder object that builds request parameters.
 212
 213 ##### Returns
 214
 215 - `Account` - *account*, Account object.
 216
 217 ----
 218
 219 #### listAccounts
 220
 221 ```java
 222 List<Account> list(Client client);
 223 ```
 224
 225 ##### Parameters
 226
 227 - `Client` - *client*, Client object that makes requests to the core.
 228
 229 ##### Returns
 230
 231 - `List of Account`, *List<Account>*, an ArrayList object contains Account objects.
 232
 233 ----
 234
 235 #### deleteAccount
 236
 237 ```java
 238 void delete(Client client, String account_info);
 239 ```
 240
 241 ##### Parameters
 242
 243 - `Client` - *client*, Client object that makes requests to the core.
 244 - `String` - *account_info*, alias or ID of account.
 245
 246 ##### Returns
 247
 248 none if the account is deleted successfully.
 249
 250 ----
 251
 252 #### createAccountReceiver
 253
 254 ```java
 255 Receiver create(Client client);
 256 ```
 257
 258 ##### Parameters
 259
 260 - `Client` - *client*, Client object that makes requests to the core.
 261
 262 ##### Returns
 263
 264 - `Receiver` - *receiver*, Receiver object.
 265
 266
 267 ----
 268
 269 #### listAddresses
 270
 271 ```java
 272 List<Address> list(Client client);
 273 ```
 274
 275 ##### Parameters
 276
 277 - `Client` - *client*, Client object that makes requests to the core.
 278
 279 ##### Returns
 280
 281 - `List of Address`, *List<Address>*, an ArrayList object contains Address objects.
 282
 283 ----
 284
 285 #### validateAddress
 286
 287 ```java
 288 Address validate(Client client, String address);
 289 ```
 290
 291 ##### Parameters
 292
 293 - `Client` - *Client*, Client object that makes requests to the core.
 294 - `String` - *address*, address of account.
 295
 296 ##### Returns
 297
 298 - `Address` - *address*, an Address object.
 299
 300
 301 ## Asset API
 302
 303
 304 #### createAsset
 305
 306 ```java
 307 Asset create(Client client);
 308 ```
 309
 310 ##### Parameters
 311
 312 - `Client` - *Client*, Client object that makes requests to the core.
 313
 314 ##### Returns
 315
 316 - `Asset` - *asset*, an Asset object.
 317
 318 ----
 319
 320 #### getAsset
 321
 322 ```java
 323 Asset get(Client client);
 324 ```
 325
 326 ##### Parameters
 327
 328 - `Client` - *Client*, Client object that makes requests to the core.
 329
 330 ##### Returns
 331
 332 - `Asset` - *asset*, an Asset object.
 333
 334 ----
 335
 336 #### listAssets
 337
 338 ```java
 339 List<Asset> list(Client client);
 340 ```
 341
 342 ##### Parameters
 343
 344 - `Client` - *Client*, Client object that makes requests to the core.
 345
 346 ##### Returns
 347
 348 - `List of Asset`, *List<Asset>*, an ArrayList object contains Asset objects.
 349
 350 ----
 351
 352 #### updateAssetAlias
 353
 354 ```java
 355 void update(Client client);
 356 ```
 357
 358 ##### Parameters
 359
 360 - `Client` - *Client*, Client object that makes requests to the core.
 361
 362 ##### Returns
 363
 364 none if the asset alias is updated success.
 365
 366 ----
 367
 368 #### listBalances
 369
 370 ```java
 371 List<Balance> list(Client client);
 372 ```
 373
 374 ##### Parameters
 375
 376 - `Client` - *Client*, Client object that makes requests to the core.
 377
 378 ##### Returns
 379
 380 - `List of Balance`, an ArrayList object contains Balance objects.
 381
 382 ----
 383
 384 #### listUnspentOutPuts
 385
 386 ```java
 387 List<UnspentOutput> list(Client client);
 388 ```
 389
 390 ##### Parameters
 391
 392 - `Client` - *Client*, Client object that makes requests to the core.
 393
 394 ##### Returns
 395
 396 - `List of UnspentOutput`, an ArrayList object contains UnspentOutput objects.
 397
 398
 399 ## Transaction API
 400
 401
 402 #### buildTransaction
 403
 404 ```java
 405 Template build(Client client);
 406 ```
 407
 408 ##### Parameters
 409
 410 - `Client` - *Client*, Client object that makes requests to the core.
 411
 412 ##### Returns
 413
 414 - `Template` - *template*, a template object.
 415
 416 ----
 417
 418 #### signTransaction
 419
 420 ```java
 421 Template sign(Client client, Template template, String password);
 422 ```
 423
 424 ##### Parameters
 425
 426 `Object`:
 427
 428 - `Client` - *Client*, Client object that makes requests to the core.
 429 - `Template` - *template*, a template object.
 430 - `String` - *password*, signature of the password.
 431
 432 ##### Returns
 433
 434 - `Template` - *template*, a template object.
 435
 436 ----
 437
 438 #### submitTransaction
 439
 440 ```java
 441 SubmitResponse submit(Client client, Template template);
 442 ```
 443
 444 ##### Parameters
 445
 446 - `Client` - *Client*, Client object that makes requests to the core.
 447 - `Template` - *template*, a template object.
 448
 449 ##### Returns
 450
 451 - `SubmitResponse` - *submitResponse*, a SubmitResponse object
 452
 453 ----
 454
 455 #### estimateTransactionGas
 456
 457 ```java
 458 TransactionGas estimateGas(Client client, Template template);
 459 ```
 460
 461 ##### Parameters
 462
 463 - `Client` - *Client*, Client object that makes requests to the core.
 464 - `Template` - *template*, a template object.
 465
 466 ##### Returns
 467
 468 - `TransactionGas` - *transactionGas*, a TransactionGas object
 469
 470 ----
 471
 472 #### getTransaction
 473
 474 ```java
 475 Transaction get(Client client);
 476 ```
 477
 478 ##### Parameters
 479
 480 - `Client` - *Client*, Client object that makes requests to the core.
 481
 482 ##### Returns
 483
 484 - `Transaction` - *transaction*, a Transaction object
 485
 486 ----
 487
 488 #### listTransactions
 489
 490 ```java
 491 List<Transaction> list(Client client);
 492 ```
 493
 494 ##### Parameters
 495
 496 - `Client` - *Client*, Client object that makes requests to the core.
 497
 498 ##### Returns
 499
 500 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 501
 502 ```java
 503 //list all transactions
 504 List<Transaction> transactionList = new Transaction.QueryBuilder().list(client);
 505 ```
 506
 507 ----
 508
 509 #### listTransactionsById
 510
 511 ```java
 512 List<Transaction> listById(Client client);
 513 ```
 514
 515 ##### Parameters
 516
 517 - `Client` - *Client*, Client object that makes requests to the core.
 518
 519 ##### Returns
 520
 521 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 522
 523 ```java
 524 String tx_id = "f04d4d9b2580ff6496f9f08d903de5a2365975fb8d65b66ca4259f152c5dd134";
 525 //list all transactions by tx_id
 526 List<Transaction> transactionList = new Transaction.QueryBuilder().setTxId(tx_id).list(client);
 527 ```
 528
 529 ----
 530
 531 #### listTransactionsByAccountId
 532
 533 ```java
 534 List<Transaction> listByAccountId(Client client);
 535 ```
 536
 537 ##### Parameters
 538
 539 - `Client` - *Client*, Client object that makes requests to the core.
 540
 541 ##### Returns
 542
 543 - `List of Transaction`, *List<Transaction>*, an ArrayList object contains Transaction objects.
 544
 545 ```java
 546 String account_id = "0E6KP8C100A02";
 547 //list all transactions by account_id
 548 List<Transaction> transactionList = new Transaction.QueryBuilder().setAccountId(account_id).list(client);
 549 ```
 550
 551 ## Wallet API
 552
 553
 554 #### backupWallet
 555
 556 ```java
 557 Wallet backupWallet(Client client);
 558 ```
 559
 560 ##### Parameters
 561
 562 - `Client` - *Client*, Client object that makes requests to the core.
 563
 564 ##### Returns
 565
 566 - `Wallet` - *wallet*, a Wallet object
 567
 568 ----
 569
 570 #### restoreWallet
 571
 572 ```java
 573 void restoreWallet(Client client ,Object accountImage, Object assetImage , Object keyImages);
 574 ```
 575
 576 ##### Parameters
 577
 578 `Object`:
 579 - `Client` - *Client*, Client object that makes requests to the core.
 580 - `Object` - *account_image*, account image.
 581 - `Object` - *asset_image*, asset image.
 582 - `Object` - *key_images*, key image.
 583
 584 ##### Returns
 585
 586 none if restore wallet success.
 587
 588
 589 ## Access Token API
 590
 591 ```java
 592 //example
 593 AccessToken accessToken = new AccessToken.Builder().setId("sheng").create(client);
 594
 595 List<AccessToken> tokenList = AccessToken.list(client);
 596
 597 String secret = "5e37378eb59de6b10e60f2247ebf71c4955002e75e0cd31ede3bf48813a0a799";
 598 AccessToken.check(client, "sheng", secret);
 599 ```
 600
 601 #### createAccessToken
 602
 603 ```java
 604 AccessToken create(Client client);
 605 ```
 606
 607 ##### Parameters
 608
 609 - `Client` - *Client*, Client object that makes requests to the core.
 610
 611 ##### Returns
 612
 613 - `AccessToken` - *accessToken*, an AccessToken object.
 614
 615 ----
 616
 617 #### listAccessTokens
 618
 619 ```java
 620 List<AccessToken> list(Client client);
 621 ```
 622
 623 ##### Parameters
 624
 625 - `Client` - *Client*, Client object that makes requests to the core.
 626
 627 ##### Returns
 628
 629 - `Array of Object`, access token array.
 630
 631 ----
 632
 633 #### deleteAccessToken
 634
 635 ```java
 636 void delete(Client client, String id);
 637 ```
 638
 639 ##### Parameters
 640
 641 - `Client` - *Client*, Client object that makes requests to the core.
 642 - `String` - *id*, token ID.
 643
 644 ##### Returns
 645
 646 none if the access token is deleted successfully.
 647
 648 ----
 649
 650 #### checkAccessToken
 651
 652 ```java
 653 void check(Client client, String id, String secret);
 654 ```
 655
 656 ##### Parameters
 657
 658 - `Client` - *Client*, Client object that makes requests to the core.
 659 - `String` - *id*, token ID.
 660 - `String` - *secret*, secret of token, the second part of the colon division for token.
 661
 662 ##### Returns
 663
 664 none if the access token is checked valid.
 665
 666
 667 ## Block API
 668
 669
 670 #### getBlockCount
 671
 672 ```java
 673 Integer getBlockCount(Client client);
 674 ```
 675
 676 ##### Parameters
 677
 678 none
 679
 680 ##### Returns
 681
 682 - `Integer` - *block_count*, recent block height of the blockchain.
 683
 684 ----
 685
 686 #### getBlockHash
 687
 688 ```java
 689 String getBlockHash(Client client);
 690 ```
 691
 692 ##### Parameters
 693
 694 none
 695
 696 ##### Returns
 697
 698 - `String` - *block_hash*, recent block hash of the blockchain.
 699
 700 ----
 701
 702 #### getBlock
 703 ```php
 704 Block getBlock(Client client);
 705 ```
 706
 707 ##### Parameters
 708
 709 - `Client` - *Client*, Client object that makes requests to the core.
 710
 711 ##### Returns
 712
 713 - `Block` - *block*, a Block object.
 714
 715 ----
 716
 717 #### getBlockHeader
 718
 719 ```java
 720 BlockHeader getBlockHeader(Client client);
 721 ```
 722
 723 ##### Parameters
 724
 725 - `Client` - *Client*, Client object that makes requests to the core.
 726
 727 ##### Returns
 728
 729 - `BlockHeader` - *blockHeader*, header of block.
 730
 731 ----
 732
 733 #### getDifficulty
 734
 735 ```java
 736 BlockDifficulty getBlockDifficulty(Client client);
 737 ```
 738
 739 ##### Parameters
 740
 741 - `Client` - *Client*, Client object that makes requests to the core.
 742
 743 ##### Returns
 744
 745 - `BlockDifficulty` - *blockDifficulty*, a BlockDifficulty object
 746
 747 ----
 748
 749 #### getHashRate
 750
 751 ```java
 752 BlockHashRate getHashRate(Client client);
 753 ```
 754
 755 ##### Parameters
 756
 757 - `Client` - *Client*, Client object that makes requests to the core.
 758
 759 ##### Returns
 760
 761 - `BlockHashRate` - *blockHashRate*, a BlockHashRate object
 762
 763 ## Mining API
 764
 765
 766 #### isMining
 767
 768 ```java
 769 Boolean isMining(Client client);
 770 ```
 771
 772 ##### Parameters
 773
 774 - `Client` - *Client*, Client object that makes requests to the core.
 775
 776 ##### Returns
 777
 778 - `Boolean` - *is_mining*, whether the node is mining.
 779
 780 ----
 781
 782 #### setMining
 783
 784 ```java
 785 void setMining(Client client, Boolean isMining);
 786 ```
 787
 788 ##### Parameters
 789
 790 - `Client` - *Client*, Client object that makes requests to the core.
 791 - `Boolean` - *is_mining*, whether the node is mining.
 792
 793
 794 ## Other API
 795
 796
 797 #### netInfo
 798
 799 ```java
 800 NetInfo getNetInfo(Client client);
 801 ```
 802
 803 ##### Parameters
 804
 805 - `Client` - *Client*, Client object that makes requests to the core.
 806
 807 ##### Returns
 808
 809 - `NetInfo` - *netInfo*, a NetInfo object.
 810
 811 ----
 812
 813 #### gasRate
 814
 815 ```java
 816 Gas gasRate(Client client);
 817 ```
 818
 819 ##### Parameters
 820
 821 - `Client` - *Client*, Client object that makes requests to the core.
 822
 823 ##### Returns
 824
 825 - `Gas` - *gas*, a Gas object.
 826
 827 ----
 828
 829 #### verifyMessage
 830
 831 ```java
 832 Boolean verifyMessage(Client client);
 833 ```
 834
 835 ##### Parameters
 836
 837 - `Client` - *Client*, Client object that makes requests to the core.
 838
 839 ##### Returns
 840
 841 - `Boolean` - *result*, verify result.
 842
 843 ----
 844
 845 #### getWork
 846
 847 ```java
 848 MinerWork getWork(Client client);
 849 ```
 850
 851 ##### Parameters
 852
 853 - `Client` - *Client*, Client object that makes requests to the core.
 854
 855 ##### Returns
 856
 857 - `MinerWork` - *minerWork*, a MinerWork object.
 858
 859 ----
 860
 861 #### submitWork
 862
 863 ```java
 864 void submiWork(Client client, String blockHeader);
 865 ```
 866
 867 ##### Parameters
 868
 869 - `Client` - *Client*, Client object that makes requests to the core.
 870 - `String` - *block_header*, raw block header.
 871
 872 ##### Returns
 873
 874 none if the work is submitted successfully.