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