diff --git a/.github/android_sample_app_screenshot.png b/.github/android_sample_app_screenshot.png new file mode 100644 index 0000000..efe7a7d Binary files /dev/null and b/.github/android_sample_app_screenshot.png differ diff --git a/docs/android.md b/docs/android.md index 13ce3fd..463e51d 100644 --- a/docs/android.md +++ b/docs/android.md @@ -1,10 +1,6 @@ # Android -This Android library is responsible for creating a new Stellar account and managing KIN balance and transactions. - -The main repository is at [github.com/kinecosystem/kin-core-android](https://github.com/kinecosystem/kin-core-android). - -## Build +## Add Kin Core SDK to your project Add this to your module's `build.gradle` file. @@ -23,30 +19,25 @@ dependencies { } ``` -For latest release version go to [https://github.com/kinecosystem/kin-core-android/releases](https://github.com/kinecosystem/kin-core-android/releases) +For latest release version go to [https://github.com/kinecosystem/kin-core-android/releases](https://github.com/kinecosystem/kin-core-android/releases). + +The main repository is at [github.com/kinecosystem/kin-core-android](https://github.com/kinecosystem/kin-core-android). -## Usage +## Get Started ### Connecting to a service provider -Create a new `KinClient` with two arguments: an android `Context` and a `ServiceProvider`. +Create a new `KinClient` with two arguments: an android `Context` and a `ServiceProvider`, optional third parameter is `storeKey` which can be used to create a multiple accounts data set, each different `storeKey` will have a separate data, an example use-case - store multiple users accounts separately. A `ServiceProvider` provides details of how to access the Stellar horizon end point. -The example below creates a `ServiceProvider` that will be used to connect to the main (production) Stellar -network +The example below creates a `ServiceProvider` that will be used to connect to the kin test network: ```java ServiceProvider horizonProvider = - new ServiceProvider("https://horizon.stellar.org", ServiceProvider.NETWORK_ID_MAIN); -KinClient kinClient = new KinClient(context, horizonProvider); + new ServiceProvider("https://horizon-kik.kininfrastructure.com", ServiceProvider.NETWORK_ID_TEST); +KinClient kinClient = new KinClient(context, horizonProvider, "user1"); ``` -To connect to a test Stellar network use the following ServiceProvider: - -```java -new ServiceProvider("https://horizon-testnet.stellar.org", ServiceProvider.NETWORK_ID_TEST) -``` - ### Creating and retrieving a KIN account The first time you use `KinClient` you need to create a new account, @@ -70,22 +61,22 @@ Calling `getAccount` with the existing account index, will retrieve the account if (kinClient.hasAccount()) { account = kinClient.getAccount(0); } -``` +``` You can delete your account from the device using `deleteAccount`, but beware! you will lose all your existing KIN if you do this. ```java kinClient.deleteAccount(int index); -``` +``` -### Onboarding +## Onboarding -A first step before an account can be used, is to create the account on Stellar blockchain, by a different entity (Server side) that has an account on Stellar network. +Before an account can be used on the configured network, it must be funded with the native network asset, +This step must be performed by a service, see [Fee token faucet service](fee-faucet.md). The second step is to activate this account on the client side, using `activate` method. The account will not be able to receive or send KIN before activation. - ```java Request activationRequest = account.activate() activationRequest.run(new ResultCallback() { @@ -99,15 +90,26 @@ activationRequest.run(new ResultCallback() { e.printStackTrace(); } }); -``` +``` + +For more details see [Onboarding](onboarding.md), also take a look at Sample App [OnBoarding](https://github.com/kinecosystem/kin-core-android/blob/dev/sample/src/main/java/kin/core/sample/OnBoarding.java) class for a complete example. + +## Account Information + +### Public Address -For a complete example of this process, take a look at Sample App `OnBoarding` class. +Your account can be identified via it's public address. To retrieve the account public address use: + +```java +account.getPublicAddress(); +``` -#### Query Account Status +### Query Account Status Current account status on the blockchain can be queried using `getStatus` method, status will be one of the following 3 options: -* `AccountStatus.NOT_CREATED` - Account is not created yet on the blockchain network. + +* `AccountStatus.NOT_CREATED` - Account is not created (funded with native asset) on the network. * `AccountStatus.NOT_ACTIVATED` - Account was created but not activated yet, the account cannot send or receive KIN yet. * `AccountStatus.ACTIVATED` - Account was created and activated, account can send and receive KIN. @@ -136,14 +138,6 @@ statusRequest.run(new ResultCallback() { }); ``` -### Public Address - -Your account can be identified via it's public address. To retrieve the account public address use: - -```java -account.getPublicAddress(); -``` - ### Retrieving Balance To retrieve the balance of your account in KIN call the `getBalance` method: @@ -164,18 +158,18 @@ balanceRequest.run(new ResultCallback() { }); ``` -### Transfering KIN to another account +## Transactions -To transfer KIN to another account, you need the public address of the account you want -to transfer the KIN to. +### Transferring KIN to another account -The following code will transfer 20 KIN to account "GDIRGGTBE3H4CUIHNIFZGUECGFQ5MBGIZTPWGUHPIEVOOHFHSCAGMEHO". +To transfer KIN to another account, you need the public address of the account you want to transfer the KIN to. + +The following code will transfer 20 KIN to account "GDIRGGTBE3H4CUIHNIFZGUECGFQ5MBGIZTPWGUHPIEVOOHFHSCAGMEHO". ```java String toAddress = "GDIRGGTBE3H4CUIHNIFZGUECGFQ5MBGIZTPWGUHPIEVOOHFHSCAGMEHO"; BigDecimal amountInKin = new BigDecimal("20"); - transactionRequest = account.sendTransaction(toAddress, amountInKin); transactionRequest.run(new ResultCallback() { @@ -194,7 +188,7 @@ transactionRequest.run(new ResultCallback() { #### Memo Arbitrary data can be added to a transfer operation using the memo parameter, -the memo is a `String` of up to 28 characters. +the memo can contain a utf-8 string up to 28 bytes in length. A typical usage is to include an order number that a service can use to verify payment. ```java String memo = "arbitrary data"; @@ -213,6 +207,8 @@ transactionRequest.run(new ResultCallback() { }); ``` +## Account Listeners + ### Listening to payments Ongoing payments in KIN, from or to an account, can be observed, @@ -230,7 +226,19 @@ ListenerRegistration listenerRegistration = account.blockchainEvents() }); ``` -For unregister the listener use `listenerRegistration.remove()` method. +### Listening to balance changes + +Account balance changes, can be observed by adding balance listener using `BlockchainEvents`: + +```java +ListenerRegistration listenerRegistration = account.blockchainEvents() + .addBalanceListener(new EventListener() { + @Override + public void onEvent(Balance balance) { + Log.d("example", "balance event, new balance is = " + balance.value().toPlainString()); + } + }); +``` ### Listening to account creation @@ -241,21 +249,19 @@ ListenerRegistration listenerRegistration = account.blockchainEvents() .addAccountCreationListener(new EventListener() { @Override public void onEvent(Void result) { - Log.d("example", "Account has created.); + Log.d("example", "Account has created.); } }); ``` -For unregister the listener use `listenerRegistration.remove()` method. +For unregister any listener use `listenerRegistration.remove()` method. -### Sync vs Async +## Sync vs Async -Asynchronous requests are supported by our `Request` object. The `request.run()` method will perform the request on a serial -background thread and notify success/failure using `ResultCallback` on the android main thread. +Asynchronous requests are supported by our `Request` object. The `request.run()` method will perform the requests sequentially on a single background thread and notify success/failure using `ResultCallback` on the android main thread. In addition, `cancel(boolean)` method can be used to safely cancel requests and detach callbacks. - -A synchronous version of these methods is also provided. Make sure you call them in a background thread. +A synchronous version (with the 'Sync' suffix) of these methods is also provided, as SDK requests performs network IO operations, make sure you call them in a background thread. ```java try { @@ -268,14 +274,58 @@ try { TransactionId transactionId = account.sendTransactionSync(toAddress, amountInKin); } catch (OperationFailedException e){ // something else went wrong - check the exception message -} +} ``` -### Sample Application +## Error Handling + +`kin-core` wraps errors with exceptions, synchronous methods can throw exceptions and asynchronous requests has `onError(Exception e)` callback. + +### Common Errors + +`AccountNotFoundException` - Account is not created (funded with native asset) on the network. +`AccountNotActivatedException` - Account was created but not activated yet, the account cannot send or receive KIN yet. +`InsufficientKinException` - Account has not enough kin funds to perform the transaction. + +## Sample Application + +![Sample App](../.github/android_sample_app_screenshot.png) -For a more detailed example on how to use the library please take a look at our [Sample App](https://github.com/kinecosystem/kin-core-android/tree/dev/sample/). +Sample app covers the entire functionality of `kin-core`, and serves as a detailed example on how to use the library. +Sample app source code can be found [here](https://github.com/kinecosystem/kin-core-android/tree/dev/sample/). -## Testing +## Building from Source + +Clone the repo: + +```bash +$ git clone https://github.com/kinecosystem/kin-core-android.git +``` + +Next, initialize and update git submodules: + +```bash +$ git submodule init && git submodule update +``` + +Now you can build the library using gradle, or open the project using Android Studio. + +### Tests + +Both Unit tests and instrumentation tests are provided, Android tests include integration tests that run on a remote test network, these tests are marked as `@LargeTest`, because they are time consuming, and depends on the network. + +### Running Tests + +For running both unit tests and instrumentation tests and generating a code coverage report using Jacoco, use `jacocoTestReport` task +```bash +$ ./gradlew jacocoTestReport +``` + +Running tests without integration tests + +```bash +$ ./gradlew jacocoTestReport -Pandroid.testInstrumentationRunnerArguments.notClass=kin.core.KinAccountIntegrationTest +``` -Both Unit tests and Android tests are provided, Android tests include integration tests that run on the Stellar test network, -these tests are marked as `@LargeTest`, because they are time consuming, and depends on the network. +Generated report can be found at: +`kin-core/build/reports/jacoco/jacocoTestReport/html/index.html`. diff --git a/docs/api-reference-overview.md b/docs/api-reference-overview.md new file mode 100644 index 0000000..fa22083 --- /dev/null +++ b/docs/api-reference-overview.md @@ -0,0 +1,7 @@ +### What platforms are supported for the Kin SDK? + +Currently [Android](android.md) and [iOS](ios.md) for mobile, and [Python](python.md) for web development. + +The mobile SDKs allow for sending and receiving KIN on your phone. + +The Python SDK allows for sending and receiving KIN on a backend app. diff --git a/docs/getting-started.md b/docs/getting-started.md index 5bc7ec8..8bf3a23 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -44,123 +44,4 @@ As mentioned, our SDKs attempt to handle and abstract all of the above (and more allowing them to focus on what's important - their product. Please see [Stellar's development guide](https://www.stellar.org/developers/guides/) for more information on Stellar internals. -Note that this knowledge is not required for you to start working with KIN on the blockchain. - -## Onboarding - -### Flow - -Onboarding a user involves the following steps: - -1. The user (client) creates an account. -1. That accounts gets fees, funded by a funding service. -1. The user activates the account for sending and receiving KIN. -1. That account gets KIN, funded by a KIN faucet service. - -### Backend Services - -For development and testing purposes, the Kin ecosystem test network provides the required funding services: - -1. [Fee token faucet service](fee-faucet.md): Funds new account with the base reserve native token, used for transactions fees. -1. [KIN faucet service](kin-faucet.md): Funds accounts with KIN. - -### Example - -We'll use the [Android SDK](android.md) as an example. -Please see [iOS](ios.md) page as well for an alternative implementation. - -```java -// Create a new `KinClient` with two arguments: an android `Context` and a `ServiceProvider`. -// -// A `ServiceProvider` provides details of how to access the Stellar horizon end point. -// The example below creates a `ServiceProvider` that will be used to connect to the main (production) Stellar -// network -ServiceProvider horizonProvider = - new ServiceProvider("https://horizon-kik.kininfrastructure.com", ServiceProvider.NETWORK_ID_MAIN); -KinClient kinClient = new KinClient(context, horizonProvider); - -// Create a KIN account. -KinAccount account; -try { - if (!kinClient.hasAccount()) { - account = kinClient.addAccount(); - } -} catch (CreateAccountException e) { - e.printStackTrace(); -} - -// Calling `getAccount` with the existing account index, will retrieve the account stored on the device. -if (kinClient.hasAccount()) { - account = kinClient.getAccount(0); -} - -// A first step before an account can be used, is to create the account on Stellar blockchain, -// by a different entity (Server side) that has an account on Stellar network. -// -// The second step is to activate this account on the client side, using `activate` method. -// The account will not be able to receive or send KIN before activation. -Request activationRequest = account.activate() -activationRequest.run(new ResultCallback() { - @Override - public void onResult(Void result) { - Log.d("example", "Account is activated"); - } - - @Override - public void onError(Exception e) { - e.printStackTrace(); - } -}); - -// Your account can be identified via it's public address. -// To retrieve the account public address use: -account.getPublicAddress(); - -// To retrieve the balance of your account in KIN call the `getBalance` method: -Request balanceRequest = account.getBalance(); -balanceRequest.run(new ResultCallback() { - - @Override - public void onResult(Balance result) { - Log.d("example", "The balance is: " + result.value(2)); - } - - @Override - public void onError(Exception e) { - e.printStackTrace(); - } -}); - -// To transfer KIN to another account, you need the public address of the account you want -// to transfer the KIN to. -// -// The following code will transfer 20 KIN to account "GDIRGGTBE3H4CUIHNIFZGUECGFQ5MBGIZTPWGUHPIEVOOHFHSCAGMEHO". -String toAddress = "GDIRGGTBE3H4CUIHNIFZGUECGFQ5MBGIZTPWGUHPIEVOOHFHSCAGMEHO"; -BigDecimal amountInKin = new BigDecimal("20"); - -transactionRequest = account.sendTransaction(toAddress, amountInKin); -transactionRequest.run(new ResultCallback() { - - @Override - public void onResult(TransactionId result) { - Log.d("example", "The transaction id: " + result.toString()); - } - - @Override - public void onError(Exception e) { - e.printStackTrace(); - } -}); - -// Ongoing payments in KIN, from or to an account, can be observed -// by adding payment listener using `BlockchainEvents`: -ListenerRegistration listenerRegistration = account.blockchainEvents() - .addPaymentListener(new EventListener() { - @Override - public void onEvent(PaymentInfo payment) { - Log.d("example", String - .format("payment event, to = %s, from = %s, amount = %s", payment.sourcePublicKey(), - payment.destinationPublicKey(), payment.amount().toPlainString()); - } - }); -``` +Note that this knowledge is not required for you to start working with KIN on the blockchain. \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index ae6834d..8869b16 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,6 +1,5 @@ -# Kin SDK -## Introduction +# Introduction ### What is Kin? @@ -20,16 +19,4 @@ The SDK allows developers to add support for sending and receiving KIN in an app It's goal is to abstract complexities surrounding blockchain technologies, and let developers focus on building a great product without worrying too much on the underlying layers. An example of some abstractions that the SDK takes care of are: -Which blockchain network is being used, Account funding, Fee management, Cryptographic seed creation, Establishing token trustlines, and more. - -### What platforms are supported for the Kin SDK? - -Currently [Android](android.md) and [iOS](ios.md) for mobile, and [Python](python.md) for web development. - -The mobile SDKs allow for sending and receiving KIN on your phone. - -The Python SDK allows for sending and receiving KIN on a backend app. - -## Getting started - -Please see [Getting Started](getting-started.md) page. +Which blockchain network is being used, Account funding, Fee management, Cryptographic seed creation, Establishing token trustlines, and more. \ No newline at end of file diff --git a/docs/kin-faucet.md b/docs/kin-faucet.md index b769efa..d492785 100644 --- a/docs/kin-faucet.md +++ b/docs/kin-faucet.md @@ -38,7 +38,7 @@ Possible alternative `"error"` values are: ### Health Check -Checks the status of the service. I most cases the returned HTTP status code is enough. +Checks the status of the service. In most cases the returned HTTP status code is enough. Nevertheless, the services replies with verbose information. ``` diff --git a/docs/links.md b/docs/links.md index a0c7a8c..6ee0f94 100644 --- a/docs/links.md +++ b/docs/links.md @@ -7,7 +7,7 @@ - [Currency](https://t.me/kincurrency) - [Technology](https://t.me/kintechnology) - Blogs - - [Kin Foundation](https://medium.com/kinfoundation) - - [Kin Contributors](https://medium.com/kin-contributors ) + - [Kin Blog](https://medium.com/kinfoundation) + - [Inside Kin](https://medium.com/inside-kin ) - [Youtube](https://www.youtube.com/channel/UCZ0z9fRKhW-GEjQs-_Jxfyg) -- [Kin Ecosystem Webiste](https://kinecosystem.org/) +- [Kin Ecosystem Website](https://kinecosystem.org/) \ No newline at end of file diff --git a/docs/network-info.md b/docs/network-info.md new file mode 100644 index 0000000..cacb982 --- /dev/null +++ b/docs/network-info.md @@ -0,0 +1,12 @@ +# Testnet Network Information + +## Configuration + +Horizon URL: [https://horizon-kik.kininfrastructure.com](https://horizon-kik.kininfrastructure.com) +Network Passphrase: `private testnet` +Kin asset issuer: `GBQ3DQOA7NF52FVV7ES3CR3ZMHUEY4LTHDAQKDTO6S546JCLFPEQGCPK` + +## Services + +Friendbot (Fee faucet): [http://friendbot-kik.kininfrastructure.com ](http://friendbot-kik.kininfrastructure.com) +Kin Faucet: [http://159.65.84.173:5000](http://159.65.84.173:5000) \ No newline at end of file diff --git a/docs/onboarding.md b/docs/onboarding.md new file mode 100644 index 0000000..86c15f6 --- /dev/null +++ b/docs/onboarding.md @@ -0,0 +1,75 @@ +# Onboarding + +### Flow + +Onboarding a user involves the following steps: + +1. The user (client) creates an account. +2. That account gets funded with native network asset (XLM) for fees, using a funding service. +3. The user activates the account for sending and receiving KIN. +4. (Optional) That account funded with KIN, using a KIN faucet service. + +### Backend Services + +For development and testing purposes, the Kin ecosystem test network provides the required funding services: + +1. [Fee token faucet service](fee-faucet.md): Funds new account with the base reserve native token, used for transactions fees. +1. [KIN faucet service](kin-faucet.md): Funds accounts with KIN. + +### Example + +We'll use the [Android SDK](android.md) as an example. +Please see [iOS](ios.md) page as well for an alternative implementation. + +Please note, This example uses blocking synchronous call (asynchronous calls exists as well) and error handling is omitted for brevity, for a complete asynchronous example see [OnBoarding class](https://github.com/kinecosystem/kin-core-android/blob/dev/sample/src/main/java/kin/core/sample/OnBoarding.java). + +```java +// Create a new `KinClient`with two arguments: +// an android `Context`and a `ServiceProvider`. +// +// A `ServiceProvider` provides details of how to access the Stellar horizon end point. The example below creates a `ServiceProvider` for connecting to the kin testnet network. +ServiceProvider horizonProvider = + new ServiceProvider("https://horizon-kik.kininfrastructure.com", ServiceProvider.NETWORK_ID_TEST); +KinClient kinClient = new KinClient(context, horizonProvider); + +// 1. The user (client) creates an account. +KinAccount account; +try { + if (!kinClient.hasAccount()) { + account = kinClient.addAccount(); + } else { + account = kinClient.getAccount(0); + } +} catch (CreateAccountException e) { + e.printStackTrace(); +} + +// 2. That accounts gets fees, funded by a funding service. +okHttpClient.newCall(new okhttp3.Request.Builder() + .url("http://friendbot-kik.kininfrastructure.com/?addr=" + account.getPublicAddress()) + .get() + .build() +) + .execute(); //handling error + +// 3. The user activates the account for sending and receiving KIN. +try { + account.activateSync(); +} catch (OperationFailedException e) { + e.printStackTrace(); +} + +// 4. That account gets KIN, funded by a KIN faucet service. +try { + okHttpClient.newCall(new okhttp3.Request.Builder() + .url("http://159.65.84.173:5000/fund?account=" + account.getPublicAddress() + "&amount=1000") + .get() + .build() + ) + .execute(); +} catch (IOException e) { + e.printStackTrace(); +} + +//now the account is funded with kin and ready for sending and receiving kin +``` diff --git a/docs/tools.md b/docs/tools.md new file mode 100644 index 0000000..48a56f1 --- /dev/null +++ b/docs/tools.md @@ -0,0 +1,9 @@ +# Tools + +## [Laboratory](http://159.65.84.173:3002/) + +Interactive way to access the Kin Blockchain. + +## [Network Dashboard](http://159.65.84.173:3001) + +Dashboard for kin testnet blockchain. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 095265f..5097c2c 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,11 +1,18 @@ site_name: Kin SDK repo_url: https://github.com/kinecosystem/kin-core-docs/ pages: - - Home: index.md - - Getting Started: getting-started.md - - Fee Faucet: fee-faucet.md - - KIN Faucet: kin-faucet.md - - Android: android.md - - iOS: ios.md - - Python: python.md - - Official Links: links.md + - Guides: + - Introduction: index.md + - Getting Started: getting-started.md + - Onboarding: onboarding.md + - Fee Faucet: fee-faucet.md + - KIN Faucet: kin-faucet.md + - Network Info: network-info.md + - Official Links: links.md + - API Reference: + - Overview: api-reference-overview.md + - Android: android.md + - iOS: ios.md + - Python: python.md + - Tools: tools.md +theme: readthedocs \ No newline at end of file