java-sdk/README.md

   1 # Bytom java-sdk
   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
   5 approach. For more information, please see Bytom API reference documentation
   6 at [Bytom wiki](https://github.com/Bytom/bytom/wiki/API-Reference)
   7
   8 ## Installation
   9
  10 ### Building from source code
  11
  12 To clone, compile, and install in your local maven repository (or copy the artifacts from the target/ directory to wherever you need them):
  13
  14 ```shell
  15 git clone https://github.com/Bytom/bytom-java-sdk.git
  16 cd java-sdk
  17 mvn package -Dmaven.test.skip=true
  18 mvn install
  19 ```
  20
  21 ## Basic Usage
  22
  23 ```java
  24 public static Client generateClient() throws BytomException {
  25     String coreURL = Configuration.getValue("bytom.api.url");
  26     String accessToken = Configuration.getValue("client.access.token");
  27     if (coreURL == null || coreURL.isEmpty()) {
  28         coreURL = "http://127.0.0.1:9888/";
  29     }
  30     return new Client(coreURL, accessToken);
  31 }
  32
  33 Client client = Client.generateClient();
  34 ```
  35 > Note: you can touch a file named ```config.properties``` in resources folder to config ```bytom.api.url``` and ```client.access.token``` by custom.
  36
  37 ## Usage
  38
  39 * [`Step 1: Create a key`](#create-a-key)
  40 * [`Step 2: Create an account`](#create-an-account)
  41 * [`Step 3: Create an receiver`](#create-an-receiver)
  42 * [`Step 4: Create an asset`](#create-an-asset)
  43 * [`Step 5: Issue asset`](#issue-asset)
  44     * [`Firstly build the transaction`](#firstly-build-the-transaction)
  45     * [`Secondly sign the transaction`](#secondly-sign-the-transaction)
  46     * [`Finally submit the transaction`](#finally-submit-the-transaction)
  47
  48 > For more details, see [API methods](https://github.com/Bytom/bytom-java-sdk/blob/master/java-sdk/doc/index.md#api-methods)
  49
  50 ### Create a key
  51
  52 ```java
  53 String alias = "test";
  54 String password = "123456";
  55
  56 Key.Builder builder = new Key.Builder().setAlias(alias).setPassword(password);
  57 Key key = Key.create(client, builder);
  58 ```
  59
  60 ### Create an account
  61
  62 ```java
  63 String alias = "sender-account";
  64 Integer quorum = 1;
  65 List<String> root_xpubs = new ArrayList<String>();
  66 root_xpubs.add(senderKey.xpub);
  67
  68 Account.Builder builder = new Account.Builder().setAlias(alias).setQuorum(quorum).setRootXpub(root_xpubs);
  69
  70 Account account = Account.create(client, builder);
  71 ```
  72
  73 ### Create an receiver
  74
  75 ```java
  76 String alias = receiverAccount.alias;
  77 String id = receiverAccount.id;
  78
  79 Account.ReceiverBuilder receiverBuilder = new Account.ReceiverBuilder().setAccountAlias(alias).setAccountId(id);
  80 Receiver receiver = receiverBuilder.create(client);
  81 ```
  82
  83 ### Create an asset
  84
  85 ```java
  86  String alias = "receiver-asset";
  87
  88 List<String> xpubs = receiverAccount.xpubs;
  89
  90 Asset.Builder builder = new Asset.Builder()
  91                         .setAlias(alias)
  92                         .setQuorum(1)
  93                         .setRootXpubs(xpubs);
  94 receiverAsset = builder.create(client);
  95 ```
  96
  97 ### Issue asset
  98
  99 For more transaction details, see [transactions](https://github.com/Bytom/bytom-java-sdk/blob/master/java-sdk/doc/transactions.md)
 100
 101 #### Firstly build the transaction
 102
 103 ```java
 104 Transaction.Template controlAddress = new Transaction.Builder()
 105         .addAction(
 106                 new Transaction.Action.SpendFromAccount()
 107                         .setAccountId(senderAccount.id)
 108                         .setAssetId(senderAsset.id)
 109                         .setAmount(300000000)
 110         )
 111         .addAction(
 112                 new Transaction.Action.ControlWithAddress()
 113                         .setAddress(receiverAddress.address)
 114                         .setAssetId(senderAsset.id)
 115                         .setAmount(200000000)
 116         ).build(client);
 117 ```
 118
 119 #### Secondly sign the transaction
 120
 121 ```java
 122 Transaction.Template singer = new Transaction.SignerBuilder().sign(client,
 123         controlAddress, "123456");
 124 ```
 125
 126 #### Finally submit the transaction
 127
 128 ```java
 129 Transaction.SubmitResponse txs = Transaction.submit(client, singer);
 130 ```
 131
 132
 133 ### All usage examples
 134
 135 For more details you can see [doc](https://github.com/Bytom/bytom-java-sdk/blob/master/doc/index.md#api-methods). And you can find Test Cases at [Junit Test Cases](https://github.com/Bytom/bytom-java-sdk/tree/master/src/test/java/io/bytom/integration)
 136
 137 ## Support and Feedback
 138
 139 If you find a bug, please submit the issue in Github directly by using [Issues](https://github.com/Bytom/bytom-java-sdk/issues)
 140
 141 ## License
 142
 143 Bytom JAVA SDK is based on the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.txt)  protocol.