From bb8e6527b66526d48c38e9440f2e3f7db4252c6c Mon Sep 17 00:00:00 2001 From: kevinfs510 Date: Fri, 21 Feb 2020 17:52:44 +0100 Subject: [PATCH 1/4] antora docs setup --- docs/antora.yml | 5 +++++ docs/modules/ROOT/_attributes.adoc | 0 docs/modules/ROOT/assets/attachments/.gitkeep | 0 docs/modules/ROOT/assets/images/.gitkeep | 0 docs/modules/ROOT/examples/.gitkeep | 0 docs/modules/ROOT/nav.adoc | 0 docs/modules/ROOT/pages/_attributes.adoc | 0 docs/modules/ROOT/pages/_partials/.gitkeep | 0 docs/modules/ROOT/pages/index.adoc | 0 9 files changed, 5 insertions(+) create mode 100644 docs/antora.yml create mode 100644 docs/modules/ROOT/_attributes.adoc create mode 100644 docs/modules/ROOT/assets/attachments/.gitkeep create mode 100644 docs/modules/ROOT/assets/images/.gitkeep create mode 100644 docs/modules/ROOT/examples/.gitkeep create mode 100644 docs/modules/ROOT/nav.adoc create mode 100644 docs/modules/ROOT/pages/_attributes.adoc create mode 100644 docs/modules/ROOT/pages/_partials/.gitkeep create mode 100644 docs/modules/ROOT/pages/index.adoc diff --git a/docs/antora.yml b/docs/antora.yml new file mode 100644 index 0000000..04f1fe2 --- /dev/null +++ b/docs/antora.yml @@ -0,0 +1,5 @@ +name: ost_wallet_sdk_ios +title: Ost Wallet SDK iOS +version: '1.0' +nav: +- modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/_attributes.adoc b/docs/modules/ROOT/_attributes.adoc new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/assets/attachments/.gitkeep b/docs/modules/ROOT/assets/attachments/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/assets/images/.gitkeep b/docs/modules/ROOT/assets/images/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/examples/.gitkeep b/docs/modules/ROOT/examples/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/pages/_attributes.adoc b/docs/modules/ROOT/pages/_attributes.adoc new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/pages/_partials/.gitkeep b/docs/modules/ROOT/pages/_partials/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..e69de29 From 412071f1d8701224a839fdacc8217187b476cd14 Mon Sep 17 00:00:00 2001 From: kevinfs510 Date: Sun, 23 Feb 2020 16:56:03 +0100 Subject: [PATCH 2/4] antora docs setup --- docs/antora.yml | 4 ++-- docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/index.adoc | 3 +++ 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/antora.yml b/docs/antora.yml index 04f1fe2..a912ca7 100644 --- a/docs/antora.yml +++ b/docs/antora.yml @@ -1,5 +1,5 @@ -name: ost_wallet_sdk_ios -title: Ost Wallet SDK iOS +name: server-sdk-java +title: Ost Server SDK Java version: '1.0' nav: - modules/ROOT/nav.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index e69de29..59a7257 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -0,0 +1 @@ +* xref:index.adoc[Overview] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index e69de29..c02665a 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -0,0 +1,3 @@ +This is the index.adoc page for OST-SDK-JAVA + +This is a test :) \ No newline at end of file From 647b459f370548ee49b5a7d04e55355a50d1746f Mon Sep 17 00:00:00 2001 From: kevinfs510 Date: Thu, 12 Mar 2020 16:22:39 +0100 Subject: [PATCH 3/4] docs setup step #2 --- docs/modules/ROOT/pages/CHANGELOG.md.adoc | 37 + docs/modules/ROOT/pages/README.md.adoc | 1026 +++++++++++++++++++++ 2 files changed, 1063 insertions(+) create mode 100644 docs/modules/ROOT/pages/CHANGELOG.md.adoc create mode 100644 docs/modules/ROOT/pages/README.md.adoc diff --git a/docs/modules/ROOT/pages/CHANGELOG.md.adoc b/docs/modules/ROOT/pages/CHANGELOG.md.adoc new file mode 100644 index 0000000..6d8c937 --- /dev/null +++ b/docs/modules/ROOT/pages/CHANGELOG.md.adoc @@ -0,0 +1,37 @@ +== https://github.com/ostdotcom/ost-sdk-java/tree/v2.2.3[OST JAVA SDK v2.2.3] + +* Added redemptions module to call user redemptions management OST APIs. +* Added redeemable SKUs module to call redeemable SKUs OST APIs. + +== https://github.com/ostdotcom/ost-sdk-java/tree/v2.2.2[OST JAVA SDK v2.2.2] + +* Readme changes for documenting new parameters in transactions module. +These parameters can help to get data between specific time interval. + +== https://github.com/ostdotcom/ost-sdk-java/tree/v2.2.0[OST JAVA SDK v2.2.0] + +* Added webhooks module to call webhook management OST APIs. +* Support for verify webhook signature. + +== https://github.com/ostdotcom/ost-sdk-java/tree/v2.1.0[OST JAVA SDK v2.1.0] + +* Added base tokens module to V2 API's + +== https://github.com/ostdotcom/ost-sdk-java/tree/v2.0.0[OST JAVA SDK v2.0.0] + +* OST API V2 interaction layer implementation. +* Removed API V0 and V1 support. +* xref:README.adoc[README.adoc] has API V2 usage instructions + +== https://github.com/ostdotcom/ost-sdk-java/tree/v1.1.0[OST JAVA SDK v1.1.0] + +* Added user balances module to V1 API's +* Added transaction ledger module to V1 API's + +== https://github.com/ostdotcom/ost-sdk-java/tree/v1.0.0[OST JAVA SDK v1.0.0] + +Initial release of the official OST JAVA SDK + + +* This release has support for interacting with V1 API along with V0 +* xref:README.adoc[README.adoc] has API V1 usage instructions +* xref:README.adoc[README_V0.adoc] has API V0 usage instructions diff --git a/docs/modules/ROOT/pages/README.md.adoc b/docs/modules/ROOT/pages/README.md.adoc new file mode 100644 index 0000000..86b3425 --- /dev/null +++ b/docs/modules/ROOT/pages/README.md.adoc @@ -0,0 +1,1026 @@ += OST Server-Side Java SDK + +image::https://travis-ci.org/ostdotcom/ost-sdk-java.svg?branch=develop[Build Status,link=https://travis-ci.org/ostdotcom/ost-sdk-java] + +https://dev.ost.com/[OST] Platform SDK for Java. + +== Introduction + +OST is a complete technology solution enabling mainstream businesses to easily launch blockchain based economies without requiring blockchain development. + +Brand Tokens (BTs) are white-label cryptocurrency tokens with utility representations running on highly-scalable Ethereum-based utility blockchains, backed by value token (such as OST, USDC) staked on Ethereum mainnet. +Within a business`s token economy, BTs can only be transferred to whitelisted user addresses. +This ensures that they stay within the token economy. + +The OST technology stack is designed to give businesses everything they need to integrate, test, and deploy BTs. +Within the OST suite of products, developers can use OST Platform to create, test, and launch Brand Tokens. + +OST APIs and server-side SDKs make it simple and easy for developers to integrate blockchain tokens into their apps. + +For documentation, visit https://dev.ost.com/ + +== Getting Started + +=== Setup Brand Token + +. Sign-up on https://platform.ost.com[OST Platform] and setup your Brand Token. +. Obtain your API Key and API Secret from https://platform.ost.com/mainnet/developer[developers page]. + +=== Installation + +==== Maven users + +Add this dependency to your project's POM + +[source,xml] +---- + + com.ost + ost-sdk-java + 2.2.1 + +---- + +==== Building from source using Maven + +Clone the repository: + +[source,bash] +---- +git clone https://github.com/ostdotcom/ost-sdk-java.git +cd ost-sdk-java +---- + +Package using MVN (without dependencies): + +[source,bash] +---- +mvn clean package -DskipTests +---- + +Package using MVN (with dependencies): + +[source,bash] +---- +mvn clean compile assembly:single -DskipTests +---- + +The jar file can be found in the target folder. + +== Usage + +* Initialize the SDK object: ++ +[source,java] +---- + // Declare connection parameters. + + // Mandatory API parameters + + String apiKey = "__abc"; // OBTAINED FROM DEVELOPER PAGE + String apiSecret = "_xyz"; // OBTAINED FROM DEVELOPER PAGE + + /* + The valid API endpoints are: + 1. Mainnet: "https://api.ost.com/mainnet/v2/" + 2. Testnet: "https://api.ost.com/testnet/v2/" + */ + + String apiEndPoint = "https://api.ost.com/testnet/v2/"; + + HashMap sdkConfig = new HashMap(); + sdkConfig.put("apiEndpoint", apiEndPoint); + sdkConfig.put("apiKey", apiKey); + sdkConfig.put("apiSecret", apiSecret); + + // Optional API parameters + + // This is the timeout in seconds for which the socket connection will remain open. + long timeoutInSeconds = 60; // The value of timeout will always be of type long. + + HashMap nestedparam = new HashMap(); + + nestedparam.put("timeout", timeoutInSeconds); + sdkConfig.put("config", nestedparam); + + // OST server side sdk object. + OSTSDK ostObj = new OSTSDK(sdkConfig); + com.ost.services.Manifest services = (com.ost.services.Manifest) ostObj.services; +---- + +=== Users Module + +* Initialize Users service object to perform user specific actions. ++ +[source,java] +---- + com.ost.services.Users usersService = services.users; +---- + +* Create User. +This creates a unique identifier for each user. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = usersService.create( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Detail using the userId obtained in user create. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom user details needs to be fetched. + String userId = "c2c__"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + JsonObject response = usersService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Users List. +Pagination is supported in this API. ++ +[source,java] +---- + // Mandatory API parameters + // No mandatory parameters. + + // Optional API parameters + + // Array of userIds for which data needs to be fetched. + ArrayList userIdsArray = new ArrayList(); + userIdsArray.add("c2c__"); + userIdsArray.add("d2c__"); + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "e77y___"; + + // Limit. + long limit = 10; + + HashMap params = new HashMap(); + params.put("ids", userIdsArray); + params.put("limit", limit); + params.put("pagination_identifier", paginationIdentifier); + + JsonObject response = usersService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Devices Module + +* Initialize Devices service object to perform device specific actions. ++ +[source,java] +---- + com.ost.services.Devices devicesService = services.devices; +---- + +* Create a Device for User. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device needs to be created. + String userId = "c2c___"; + + // Device address of user's device. + String deviceAddress = "0x1Ea___"; + + // Device API signer address. + String apiSignerAddress = "0x5F8___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("address", deviceAddress); + params.put("api_signer_address", apiSignerAddress); + + JsonObject response = devicesService.create( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Device Detail using userId and deviceAddress. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device details needs to be fetched. + String userId = "c2c___"; + + // Device address of user's device. + String deviceAddress = "0x1E___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("device_address", deviceAddress); + + JsonObject response = devicesService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Devices List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device details needs to be fetched. + String userId = "c2c6___"; + + // Optional API parameters + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJ___"; + + // Array of device addresses of end user. + ArrayList deviceAddressesArray = new ArrayList(); + deviceAddressesArray.add("0x59___"); + deviceAddressesArray.add("0xab___"); + + // Limit. + long limit = 10; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("addresses", deviceAddressesArray); + params.put("pagination_identifier", paginationIdentifier); + params.put("limit", limit); + + JsonObject response = devicesService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Device Managers Module + +* Initialize Device Manager service object to perform device manager specific actions. ++ +[source,java] +---- + com.ost.services.DeviceManagers deviceManagersService = services.deviceManagers; +---- + +* Get Device Manager Detail using userId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device manager details needs to be fetched. + String userId = "c2c___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + + JsonObject response = deviceManagersService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Sessions Module + +* Initialize Sessions service object to perform session specific actions. ++ +[source,java] +---- + com.ost.services.Sessions sessionsService = services.sessions; +---- + +* Get User Session Detail using userId and session address. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom session details needs to be fetched. + String userId = "c2c___"; + + // Session address of user for which details needs to be fetched. + String sessionAddress = "0x1Ea___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("session_address", sessionAddress); + + JsonObject response = sessionsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Sessions List using userId. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom session details needs to be fetched. + String userId = "c2c___"; + + // Optional API parameters: + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJs___"; + + // Array of session addresses of end user. + ArrayList sessionAddressesArray = new ArrayList(); + sessionAddressesArray.add("0x59___"); + sessionAddressesArray.add("0xab___"); + + // Limit. + long limit = 10; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("pagination_identifier", paginationIdentifier); + params.put("addresses", sessionAddressesArray); + params.put("limit", limit); + + JsonObject response = sessionsService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Executing Transactions + +For executing transactions, you need to understand the 4 modules described below. + +==== Rules Module + +* Initialize Rules service object to perform rules specific actions. ++ +[source,java] +---- + com.ost.services.Rules rulesService = services.rules; +---- + +* List Rules. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = rulesService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +==== Price Points Module + +* Initialize Price Points service object to perform price points specific actions. ++ +[source,java] +---- + com.ost.services.PricePoints pricePointsService = services.pricePoints; +---- + +* Get Price Points Detail. ++ +[source,java] +---- + // Mandatory API parameters + + // ChainId of your brand token economy. + long chainId = 2000; + + HashMap params = new HashMap(); + params.put("chain_id", chainId); + + JsonObject response = pricePointsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +==== Transactions Module + +* Initialize Transactions service object to perform transaction specific actions. ++ +[source,java] +---- + com.ost.services.Transactions transactionsService = services.transactions; +---- + +* DIRECT-TRANSFERS execute transaction should be used to transfer BTs to your end-users. ++ +[source,java] +---- + // Mandatory API parameters + + // Token holder address of receiver. + String transferToAddress = "0xa3___"; + + // Amount of tokens to be transferred. + String transferAmount = "1"; + + // Company userId. + String companyUserId = "ee89___"; + + // Address of DirectTransfer rule. Use list rules API of Rules module to get the address of rules. + // In the rules array which you will get in response, use the address having name "Direct Transfer". + String directTransferRuleAddress = "0xe379___"; + + // Parameters required for rule execution. + ArrayList arrayListForReceiverTokenHolderAddress = new ArrayList(); + arrayListForReceiverTokenHolderAddress.add(transferToAddress); + + ArrayList arrayListAmount = new ArrayList(); + arrayListAmount.add(transferAmount); + + ArrayList nestedArraylist = new ArrayList(); + nestedArraylist.add(arrayListForReceiverTokenHolderAddress); + nestedArraylist.add(arrayListAmount); + + // Parameters required for rule execution. + HashMap nestedparams = new HashMap(); + nestedparams.put("method", "directTransfers"); // Rule name which needs to be passed as-is. + nestedparams.put("parameters", nestedArraylist); + + Gson gsonObj = new Gson(); + String jsonStr = gsonObj.toJson(nestedparams); + + + HashMap params = new HashMap(); + + params.put("user_id", companyUserId); + params.put("to", directTransferRuleAddress); + params.put("raw_calldata", jsonStr); + + // Optional API parameters + + // Name of the transaction. Eg. "like", "download", etc. + // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) + String transactionName = "like"; + + // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". + String transactionType = "company_to_user"; + + // Some extra information about transaction. + // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) + String details = "lorem_ipsum"; + + // Additional transaction information. There is no dependency between any of the metaProperty keys. + // However, if a key is present, its value cannot be null or undefined. + HashMap metaProperty = new HashMap(); + metaProperty.put("name", transactionName); + metaProperty.put("type", transactionType); + metaProperty.put("details", details); + + params.put("meta_property", metaProperty); + + JsonObject response = transactionsService.execute( params ); + System.out.println("response: " + response.toString() ); +---- + +* PAY Execute Transaction should be used when transactions of BTs equivalent to some fiat amount need to be executed. ++ +[source,java] +---- + // Mandatory API parameters + + // Token holder address of receiver. + String transferToAddress = "0xa31__"; + + // Company token holder address. + String companyTokenHolderAddress = "0xa963___"; + + + // Pay currency code. Supported currency codes are "USD", "EUR" and "GBP". + String payCurrencyCode = "USD"; + + // In pay transaction, the transfer amounts are in pay currency (fiat currency like USD) which then are converted + // into tokens. Use get price point detail API of Price Points module to get this value. + double pricePoint = 0.020606673; + + // Price point needs to be passed in atto. Multiply the price point with 10^18. Also, this value should be a string. + BigDecimal intendedPricePointBD = new BigDecimal(pricePoint).multiply((new BigDecimal(10)).pow(18)); + String intendedPricePointInAtto = intendedPricePointBD.toString().split("\\.")[0]; + + // Amount of Fiat to be transferred. + double transferAmountInFiat = 0.1; + + // Transfer amount in wei needs to be passed in atto. Multiply the fiat transfer amount with 10^18. Also, this value should be a string. + BigDecimal fiatTransferAmountInWeiBD = new BigDecimal(transferAmountInFiat).multiply((new BigDecimal(10)).pow(18)); + String fiatTransferAmountInAtto = fiatTransferAmountInWeiBD.toString().split("\\.")[0]; + + // Parameters required for rule execution. + ArrayList arrayListForReceiverTokenHolderAddress = new ArrayList(); + arrayListForReceiverTokenHolderAddress.add(transferToAddress); + + ArrayList arrayListAmount = new ArrayList(); + arrayListAmount.add(fiatTransferAmountInAtto); + Gson gsonObj = new Gson(); + + ArrayList nestedArraylist = new ArrayList(); + nestedArraylist.add(companyTokenHolderAddress); + nestedArraylist.add(arrayListForReceiverTokenHolderAddress); + nestedArraylist.add(arrayListAmount); + nestedArraylist.add(payCurrencyCode); + nestedArraylist.add(intendedPricePointInAtto); + + HashMap nestedparams = new HashMap(); + nestedparams.put("method", "pay"); // Rule name which needs to be passed as-is. + nestedparams.put("parameters", nestedArraylist); + + String jsonRawCallData = gsonObj.toJson(nestedparams); + + // Company userId. + String companyUserId = "ee8___"; + + // Address of Pay rule. Use list rules API to get the address of rules. + // In the rules array which you will get in response, use the address having name "Pricer". + String payRuleAddress = "0xe37___"; + + /* Optional API parameters: */ + + // Name of the transaction. Eg. "like", "download", etc. + // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) + String transactionName = "like"; + + // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". + String transactionType = "company_to_user"; + + // Some extra information about transaction. + // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) + String details = "lorem_ipsum"; + + HashMap metaProperty = new HashMap(); + metaProperty.put("name", transactionName); + metaProperty.put("type", transactionType); + metaProperty.put("details", details); + + + HashMap params = new HashMap(); + params.put("user_id", companyUserId); + params.put("to", payRuleAddress); + + params.put("meta_property", metaProperty); + params.put("raw_calldata", jsonRawCallData); + + JsonObject response = transactionsService.execute( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Transaction Detail using userId and transactionId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of end-user. + String userId = "ee8___"; + + // Unique identifier of the transaction to be retrieved. + String transactionId = "f1d___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("transaction_id", transactionId); + + JsonObject response = transactionsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Transactions using userId. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of end-user. + String userId = "ee89___"; + + // Optional API parameters + + // Array of status values. + ArrayList statusesArray = new ArrayList(); + statusesArray.add("CREATED"); + statusesArray.add("SUBMITTED"); + statusesArray.add("SUCCESS"); + statusesArray.add("FAILED"); + + // To get transactions between a specific time interval, add start timestamp and end timestamp. + long startTime = 1563260786; + long endTime = 1563280786; + + // Name of the transaction. Eg. "like", "download", etc. + // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) + String transactionName = "like"; + + // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". + String transactionType = "company_to_user"; + + // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) + String details = "lorem_ipsum"; + + // Additional transaction information. There is no dependency between any of the metaProperty keys. + // However, if a key is present, its value cannot be null or undefined. + ArrayList> metaPropertyArray = new ArrayList>(); + HashMap metaPropertyArrayParams = new HashMap(); + metaPropertyArrayParams.put("name", transactionName); + metaPropertyArrayParams.put("type", transactionType); + metaPropertyArrayParams.put("details", details); + metaPropertyArray.add(metaPropertyArrayParams); + + Gson gsonObj = new Gson(); + String metaPropertyArrayJsonStr = gsonObj.toJson(metaPropertyArray); + + // Limit. + long limit = 10; + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJsY___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("start_time", startTime); + params.put("end_time", endTime); + params.put("statuses", statusesArray); + params.put("meta_properties", metaPropertyArrayJsonStr); + params.put("limit", limit); + params.put("pagination_identifier", paginationIdentifier); + + JsonObject response = transactionsService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +==== Balances Module + +* Initialize Balances service object to perform balances specific actions. ++ +[source,java] +---- + com.ost.services.Balance balancesService = services.balance; +---- + +* Get User Balance using userId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId for whom balance needs to be fetched. + String userId = "c2c6___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + + JsonObject response = balancesService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Recovery Owners Module + +* Initialize Recovery Owners service object to perform recovery owners specific actions. ++ +[source,java] +---- + com.ost.services.RecoveryOwners recoveryOwnersService = services.recoveryOwners; +---- + +* Get Recovery Owner Detail using userId and recovery owner address. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId for whom recovery details needs to be fetched. + String userId = "c2c___"; + + // Recovery address of user. + String recoveryOwnerAddress = "0xe37___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("recovery_owner_address", recoveryOwnerAddress); + + JsonObject response = recoveryOwnersService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Tokens Module + +* Initialize Tokens service object to perform tokens specific actions. ++ +[source,java] +---- + com.ost.services.Tokens tokensService = services.tokens; +---- + +* Get Token Detail. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = tokensService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Chains Module + +* Initialize Chains service object to perform chains specific actions. ++ +[source,java] +---- + com.ost.services.Chains chainsService = services.chains; +---- + +* Get Chain Detail using chainId. ++ +[source,java] +---- + // Mandatory API parameters + + // ChainId for which details needs to be fetched. Only origin chainId and OST-specific auxiliary chainIds are allowed. + String chainId = "2000"; + + HashMap params = new HashMap(); + params.put("chain_id", chainId); + + JsonObject response = chainsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Base Tokens Module + +* Initialize Base Tokens service object to perform base tokens specific actions. ++ +[source,java] +---- + com.ost.services.BaseTokens baseTokensService = services.baseTokens; +---- + +* Get Base Tokens Detail. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = baseTokensService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Webhooks Module + +* Initialize Webhooks service object to perform webhooks specific actions. ++ +[source,java] +---- + com.ost.services.Webhooks webhooksService = services.webhooks; +---- + +* Create Webhook using the topics and the subscription url. ++ +[source,java] +---- + // Mandatory API parameters + + // Array of topics. + ArrayList topicParams = new ArrayList(); + topicParams.add("transactions/initiate"); + topicParams.add("transactions/success"); + + // URL where you want to receive the event notifications. + String url = "https://www.testingWebhooks.com"; + + // Optional API parameters + + // Status of a webhook. Possible values are "active" and "inactive". + String status = "active"; + + HashMap params = new HashMap(); + params.put("url", url); + params.put("status", status); + params.put("topics", topicParams); + + JsonObject response = webhooksService.create( params ); + System.out.println("response: " + response.toString() ); +---- + +* Update existing Webhook using a webhookId and an array of topics. ++ +[source,java] +---- + // Mandatory API parameters + + // Array of topics. + ArrayList topicParams = new ArrayList(); + topicParams.add("transactions/initiate"); + topicParams.add("transactions/success"); + + // Unique identifier for a webhook. + String webhookId = "a743___"; + + // Optional API parameters + + // Status of a webhook. Possible values are "active" and "inactive". + String status = "active"; + + HashMap params = new HashMap(); + params.put("webhook_id", webhookId); + params.put("status", status); + params.put("topics", topicParams); + + JsonObject response = webhooksService.update( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Webhook using webhookId. ++ +[source,java] +---- + // Mandatory API parameters + + // Unique identifier for a webhook. + String webhookId = "a743___"; + + + HashMap params = new HashMap(); + params.put("webhook_id", webhookId); + + JsonObject response = webhooksService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Webhook List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + // No mandatory parameters. + + // Optional API parameters + + // Limit. + long limit = 10; + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJwY___"; + + HashMap params = new HashMap(); + params.put("limit", limit); + params.put("pagination_identifier", paginationIdentifier); + + JsonObject response = webhooksService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +* Delete Webhook using webhookId. ++ +[source,java] +---- + // Mandatory API parameters + + // Unique identifier for a webhook. + String webhookId = "a743___"; + + HashMap params = new HashMap(); + params.put("webhook_id", webhookId); + + JsonObject response = webhooksService.deleteWebhook( params ); + System.out.println("response: " + response.toString() ); +---- + +* Verify webhook request signature. +This can be used to validate if the webhook received at your end from OST platform is correctly signed. ++ +[source,java] +---- + // Webhook data obtained. + String webhookEventData = "{\"id\":\"54e3cd1c-afd7-4dcf-9c78-137c56a53582\",\"topic\":\"transactions/success\",\"created_at\":1560838772,\"webhook_id\":\"0823a4ea-5d87-44cf-8ca8-1e5a31bf8e46\",\"version\":\"v2\",\"data\":{\"result_type\":\"transaction\",\"transaction\":{\"id\":\"ddebe817-b94f-4b51-9227-f543fae4715a\",\"transaction_hash\":\"0x7ee737db22b58dc4da3f4ea4830ca709b388d84f31e77106cb79ee09fc6448f9\",\"from\":\"0x69a581096dbddf6d1e0fff7ebc1254bb7a2647c6\",\"to\":\"0xc2f0dde92f6f3a3cb13bfff43e2bd136f7dcfe47\",\"nonce\":3,\"value\":\"0\",\"gas_price\":\"1000000000\",\"gas_used\":120558,\"transaction_fee\":\"120558000000000\",\"block_confirmation\":24,\"status\":\"SUCCESS\",\"updated_timestamp\":1560838699,\"block_timestamp\":1560838698,\"block_number\":1554246,\"rule_name\":\"Pricer\",\"meta_property\":{},\"transfers\":[{\"from\":\"0xc2f0dde92f6f3a3cb13bfff43e2bd136f7dcfe47\",\"from_user_id\":\"acfdea7d-278e-4ffc-aacb-4a21398a280c\",\"to\":\"0x0a754aaab96d634337aac6556312de396a0ca46a\",\"to_user_id\":\"7bc8e0bd-6761-4604-8f8e-e33f86f81309\",\"amount\":\"112325386\",\"kind\":\"transfer\"}]}}}"; + + // Get webhoook version from webhook events data. + String version = "v2"; + + // Get ost-timestamp from the response received in event. + String requestTimestamp = "1559902637"; + + // Get signature from the response received in event. + String signature = "2c56c143550c603a6ff47054803f03ee4755c9c707986ae27f7ca1dd1c92a824"; + + String webhookSecret = "mySecret"; + String stringifiedData = webhookEventData; + + Boolean response = webhooksService.verifySignature( version, stringifiedData, requestTimestamp, signature, webhookSecret ); + System.out.println("response: " + response ); +---- + +=== Redemption Modules + +Two modules of redemption, "Redeemable SKUs" and "User Redemptions", are described below. + +==== Redeemable SKUs Module + +* Initialize Redeemable SKUs service object to perform redeemable skus specific actions. ++ +[source,java] +---- + com.ost.services.RedeemableSkus redeemableSkusService = services.redeemableSkus; +---- + +* Get Redeemable SKU detail using the redeemable sku id. ++ +[source,java] +---- + // Mandatory API parameters + + // Fetch details of following redeemable sku. + String redeemableSkuId = 'c2c__'; + + HashMap params = new HashMap(); + params.put("redeemable_sku_id", redeemableSkuId); + + JsonObject response = redeemableSkusService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Redeemable SKUs List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + // NOTE: No mandatory parameters. + + // Optional API parameters + + // Limit. + long limit = 10; + + // Array of redeemable SKU ids. + ArrayList redemptionSkuIdsArray = new ArrayList(); + redemptionSkuIdsArray.add("1001"); + redemptionSkuIdsArray.add("1002"); + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJ___"; + + HashMap params = new HashMap(); + params.put("redemption_ids", redemptionSkuIdsArray); + params.put("pagination_identifier", paginationIdentifier); + params.put("limit", limit); + + JsonObject response = redeemableSkusService.getList( params ); + System.out.println("response: " + response.toString() ); +---- ++ +==== User Redemptions Module + +* Initialize Redemptions service object to perform user redemption specific actions. ++ +[source,java] +---- + com.ost.services.Redemptions redemptionsService = services.redemptions; +---- + +* Get User redemption details using the userId and redemptionId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom redemption details needs to be fetched. + String userId = "c2c6___"; + + // Unique identifier of the redemption of user. + String redemptionId = "c2c___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("redemption_id", redemptionId); + + JsonObject response = redemptionsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Redemptions List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + String userId = "c2c6___"; + + // Optional API parameters + + // Limit. + long limit = 10; + + // Array of user redemption uuids. + ArrayList redemptionIdsArray = new ArrayList(); + redemptionIdsArray.add("eyJ___"); + redemptionIdsArray.add("eyJ___"); + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJ___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("redemption_ids", redemptionIdsArray); + params.put("pagination_identifier", paginationIdentifier); + params.put("limit", limit); + + JsonObject response = redemptionsService.getList( params ); + System.out.println("response: " + response.toString() ); +---- From 4b764315d48863fa3b0f42b48f1b721fda5f7ec7 Mon Sep 17 00:00:00 2001 From: kevinfs510 Date: Thu, 12 Mar 2020 17:25:59 +0100 Subject: [PATCH 4/4] docs setup step #3 --- docs/modules/ROOT/nav.adoc | 3 +- .../{CHANGELOG.md.adoc => CHANGELOG.adoc} | 0 docs/modules/ROOT/pages/README.md.adoc | 1026 ---------------- docs/modules/ROOT/pages/index.adoc | 1027 ++++++++++++++++- 4 files changed, 1027 insertions(+), 1029 deletions(-) rename docs/modules/ROOT/pages/{CHANGELOG.md.adoc => CHANGELOG.adoc} (100%) delete mode 100644 docs/modules/ROOT/pages/README.md.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 59a7257..df24086 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1 +1,2 @@ -* xref:index.adoc[Overview] \ No newline at end of file +* xref:index.adoc[Overview] +* xref:CHANGELOG.adoc[Change Log] \ No newline at end of file diff --git a/docs/modules/ROOT/pages/CHANGELOG.md.adoc b/docs/modules/ROOT/pages/CHANGELOG.adoc similarity index 100% rename from docs/modules/ROOT/pages/CHANGELOG.md.adoc rename to docs/modules/ROOT/pages/CHANGELOG.adoc diff --git a/docs/modules/ROOT/pages/README.md.adoc b/docs/modules/ROOT/pages/README.md.adoc deleted file mode 100644 index 86b3425..0000000 --- a/docs/modules/ROOT/pages/README.md.adoc +++ /dev/null @@ -1,1026 +0,0 @@ -= OST Server-Side Java SDK - -image::https://travis-ci.org/ostdotcom/ost-sdk-java.svg?branch=develop[Build Status,link=https://travis-ci.org/ostdotcom/ost-sdk-java] - -https://dev.ost.com/[OST] Platform SDK for Java. - -== Introduction - -OST is a complete technology solution enabling mainstream businesses to easily launch blockchain based economies without requiring blockchain development. - -Brand Tokens (BTs) are white-label cryptocurrency tokens with utility representations running on highly-scalable Ethereum-based utility blockchains, backed by value token (such as OST, USDC) staked on Ethereum mainnet. -Within a business`s token economy, BTs can only be transferred to whitelisted user addresses. -This ensures that they stay within the token economy. - -The OST technology stack is designed to give businesses everything they need to integrate, test, and deploy BTs. -Within the OST suite of products, developers can use OST Platform to create, test, and launch Brand Tokens. - -OST APIs and server-side SDKs make it simple and easy for developers to integrate blockchain tokens into their apps. - -For documentation, visit https://dev.ost.com/ - -== Getting Started - -=== Setup Brand Token - -. Sign-up on https://platform.ost.com[OST Platform] and setup your Brand Token. -. Obtain your API Key and API Secret from https://platform.ost.com/mainnet/developer[developers page]. - -=== Installation - -==== Maven users - -Add this dependency to your project's POM - -[source,xml] ----- - - com.ost - ost-sdk-java - 2.2.1 - ----- - -==== Building from source using Maven - -Clone the repository: - -[source,bash] ----- -git clone https://github.com/ostdotcom/ost-sdk-java.git -cd ost-sdk-java ----- - -Package using MVN (without dependencies): - -[source,bash] ----- -mvn clean package -DskipTests ----- - -Package using MVN (with dependencies): - -[source,bash] ----- -mvn clean compile assembly:single -DskipTests ----- - -The jar file can be found in the target folder. - -== Usage - -* Initialize the SDK object: -+ -[source,java] ----- - // Declare connection parameters. - - // Mandatory API parameters - - String apiKey = "__abc"; // OBTAINED FROM DEVELOPER PAGE - String apiSecret = "_xyz"; // OBTAINED FROM DEVELOPER PAGE - - /* - The valid API endpoints are: - 1. Mainnet: "https://api.ost.com/mainnet/v2/" - 2. Testnet: "https://api.ost.com/testnet/v2/" - */ - - String apiEndPoint = "https://api.ost.com/testnet/v2/"; - - HashMap sdkConfig = new HashMap(); - sdkConfig.put("apiEndpoint", apiEndPoint); - sdkConfig.put("apiKey", apiKey); - sdkConfig.put("apiSecret", apiSecret); - - // Optional API parameters - - // This is the timeout in seconds for which the socket connection will remain open. - long timeoutInSeconds = 60; // The value of timeout will always be of type long. - - HashMap nestedparam = new HashMap(); - - nestedparam.put("timeout", timeoutInSeconds); - sdkConfig.put("config", nestedparam); - - // OST server side sdk object. - OSTSDK ostObj = new OSTSDK(sdkConfig); - com.ost.services.Manifest services = (com.ost.services.Manifest) ostObj.services; ----- - -=== Users Module - -* Initialize Users service object to perform user specific actions. -+ -[source,java] ----- - com.ost.services.Users usersService = services.users; ----- - -* Create User. -This creates a unique identifier for each user. -+ -[source,java] ----- - HashMap params = new HashMap(); - JsonObject response = usersService.create( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get User Detail using the userId obtained in user create. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom user details needs to be fetched. - String userId = "c2c__"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - JsonObject response = usersService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get Users List. -Pagination is supported in this API. -+ -[source,java] ----- - // Mandatory API parameters - // No mandatory parameters. - - // Optional API parameters - - // Array of userIds for which data needs to be fetched. - ArrayList userIdsArray = new ArrayList(); - userIdsArray.add("c2c__"); - userIdsArray.add("d2c__"); - - // Pagination identifier from the previous API call response. Not needed for page one. - String paginationIdentifier = "e77y___"; - - // Limit. - long limit = 10; - - HashMap params = new HashMap(); - params.put("ids", userIdsArray); - params.put("limit", limit); - params.put("pagination_identifier", paginationIdentifier); - - JsonObject response = usersService.getList( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Devices Module - -* Initialize Devices service object to perform device specific actions. -+ -[source,java] ----- - com.ost.services.Devices devicesService = services.devices; ----- - -* Create a Device for User. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom device needs to be created. - String userId = "c2c___"; - - // Device address of user's device. - String deviceAddress = "0x1Ea___"; - - // Device API signer address. - String apiSignerAddress = "0x5F8___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("address", deviceAddress); - params.put("api_signer_address", apiSignerAddress); - - JsonObject response = devicesService.create( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get User Device Detail using userId and deviceAddress. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom device details needs to be fetched. - String userId = "c2c___"; - - // Device address of user's device. - String deviceAddress = "0x1E___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("device_address", deviceAddress); - - JsonObject response = devicesService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get User Devices List. -Pagination is supported by this API. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom device details needs to be fetched. - String userId = "c2c6___"; - - // Optional API parameters - - // Pagination identifier from the previous API call response. Not needed for page one. - String paginationIdentifier = "eyJ___"; - - // Array of device addresses of end user. - ArrayList deviceAddressesArray = new ArrayList(); - deviceAddressesArray.add("0x59___"); - deviceAddressesArray.add("0xab___"); - - // Limit. - long limit = 10; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("addresses", deviceAddressesArray); - params.put("pagination_identifier", paginationIdentifier); - params.put("limit", limit); - - JsonObject response = devicesService.getList( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Device Managers Module - -* Initialize Device Manager service object to perform device manager specific actions. -+ -[source,java] ----- - com.ost.services.DeviceManagers deviceManagersService = services.deviceManagers; ----- - -* Get Device Manager Detail using userId. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom device manager details needs to be fetched. - String userId = "c2c___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - - JsonObject response = deviceManagersService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Sessions Module - -* Initialize Sessions service object to perform session specific actions. -+ -[source,java] ----- - com.ost.services.Sessions sessionsService = services.sessions; ----- - -* Get User Session Detail using userId and session address. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom session details needs to be fetched. - String userId = "c2c___"; - - // Session address of user for which details needs to be fetched. - String sessionAddress = "0x1Ea___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("session_address", sessionAddress); - - JsonObject response = sessionsService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get User Sessions List using userId. -Pagination is supported by this API. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom session details needs to be fetched. - String userId = "c2c___"; - - // Optional API parameters: - - // Pagination identifier from the previous API call response. Not needed for page one. - String paginationIdentifier = "eyJs___"; - - // Array of session addresses of end user. - ArrayList sessionAddressesArray = new ArrayList(); - sessionAddressesArray.add("0x59___"); - sessionAddressesArray.add("0xab___"); - - // Limit. - long limit = 10; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("pagination_identifier", paginationIdentifier); - params.put("addresses", sessionAddressesArray); - params.put("limit", limit); - - JsonObject response = sessionsService.getList( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Executing Transactions - -For executing transactions, you need to understand the 4 modules described below. - -==== Rules Module - -* Initialize Rules service object to perform rules specific actions. -+ -[source,java] ----- - com.ost.services.Rules rulesService = services.rules; ----- - -* List Rules. -+ -[source,java] ----- - HashMap params = new HashMap(); - JsonObject response = rulesService.getList( params ); - System.out.println("response: " + response.toString() ); ----- - -==== Price Points Module - -* Initialize Price Points service object to perform price points specific actions. -+ -[source,java] ----- - com.ost.services.PricePoints pricePointsService = services.pricePoints; ----- - -* Get Price Points Detail. -+ -[source,java] ----- - // Mandatory API parameters - - // ChainId of your brand token economy. - long chainId = 2000; - - HashMap params = new HashMap(); - params.put("chain_id", chainId); - - JsonObject response = pricePointsService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -==== Transactions Module - -* Initialize Transactions service object to perform transaction specific actions. -+ -[source,java] ----- - com.ost.services.Transactions transactionsService = services.transactions; ----- - -* DIRECT-TRANSFERS execute transaction should be used to transfer BTs to your end-users. -+ -[source,java] ----- - // Mandatory API parameters - - // Token holder address of receiver. - String transferToAddress = "0xa3___"; - - // Amount of tokens to be transferred. - String transferAmount = "1"; - - // Company userId. - String companyUserId = "ee89___"; - - // Address of DirectTransfer rule. Use list rules API of Rules module to get the address of rules. - // In the rules array which you will get in response, use the address having name "Direct Transfer". - String directTransferRuleAddress = "0xe379___"; - - // Parameters required for rule execution. - ArrayList arrayListForReceiverTokenHolderAddress = new ArrayList(); - arrayListForReceiverTokenHolderAddress.add(transferToAddress); - - ArrayList arrayListAmount = new ArrayList(); - arrayListAmount.add(transferAmount); - - ArrayList nestedArraylist = new ArrayList(); - nestedArraylist.add(arrayListForReceiverTokenHolderAddress); - nestedArraylist.add(arrayListAmount); - - // Parameters required for rule execution. - HashMap nestedparams = new HashMap(); - nestedparams.put("method", "directTransfers"); // Rule name which needs to be passed as-is. - nestedparams.put("parameters", nestedArraylist); - - Gson gsonObj = new Gson(); - String jsonStr = gsonObj.toJson(nestedparams); - - - HashMap params = new HashMap(); - - params.put("user_id", companyUserId); - params.put("to", directTransferRuleAddress); - params.put("raw_calldata", jsonStr); - - // Optional API parameters - - // Name of the transaction. Eg. "like", "download", etc. - // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) - String transactionName = "like"; - - // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". - String transactionType = "company_to_user"; - - // Some extra information about transaction. - // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) - String details = "lorem_ipsum"; - - // Additional transaction information. There is no dependency between any of the metaProperty keys. - // However, if a key is present, its value cannot be null or undefined. - HashMap metaProperty = new HashMap(); - metaProperty.put("name", transactionName); - metaProperty.put("type", transactionType); - metaProperty.put("details", details); - - params.put("meta_property", metaProperty); - - JsonObject response = transactionsService.execute( params ); - System.out.println("response: " + response.toString() ); ----- - -* PAY Execute Transaction should be used when transactions of BTs equivalent to some fiat amount need to be executed. -+ -[source,java] ----- - // Mandatory API parameters - - // Token holder address of receiver. - String transferToAddress = "0xa31__"; - - // Company token holder address. - String companyTokenHolderAddress = "0xa963___"; - - - // Pay currency code. Supported currency codes are "USD", "EUR" and "GBP". - String payCurrencyCode = "USD"; - - // In pay transaction, the transfer amounts are in pay currency (fiat currency like USD) which then are converted - // into tokens. Use get price point detail API of Price Points module to get this value. - double pricePoint = 0.020606673; - - // Price point needs to be passed in atto. Multiply the price point with 10^18. Also, this value should be a string. - BigDecimal intendedPricePointBD = new BigDecimal(pricePoint).multiply((new BigDecimal(10)).pow(18)); - String intendedPricePointInAtto = intendedPricePointBD.toString().split("\\.")[0]; - - // Amount of Fiat to be transferred. - double transferAmountInFiat = 0.1; - - // Transfer amount in wei needs to be passed in atto. Multiply the fiat transfer amount with 10^18. Also, this value should be a string. - BigDecimal fiatTransferAmountInWeiBD = new BigDecimal(transferAmountInFiat).multiply((new BigDecimal(10)).pow(18)); - String fiatTransferAmountInAtto = fiatTransferAmountInWeiBD.toString().split("\\.")[0]; - - // Parameters required for rule execution. - ArrayList arrayListForReceiverTokenHolderAddress = new ArrayList(); - arrayListForReceiverTokenHolderAddress.add(transferToAddress); - - ArrayList arrayListAmount = new ArrayList(); - arrayListAmount.add(fiatTransferAmountInAtto); - Gson gsonObj = new Gson(); - - ArrayList nestedArraylist = new ArrayList(); - nestedArraylist.add(companyTokenHolderAddress); - nestedArraylist.add(arrayListForReceiverTokenHolderAddress); - nestedArraylist.add(arrayListAmount); - nestedArraylist.add(payCurrencyCode); - nestedArraylist.add(intendedPricePointInAtto); - - HashMap nestedparams = new HashMap(); - nestedparams.put("method", "pay"); // Rule name which needs to be passed as-is. - nestedparams.put("parameters", nestedArraylist); - - String jsonRawCallData = gsonObj.toJson(nestedparams); - - // Company userId. - String companyUserId = "ee8___"; - - // Address of Pay rule. Use list rules API to get the address of rules. - // In the rules array which you will get in response, use the address having name "Pricer". - String payRuleAddress = "0xe37___"; - - /* Optional API parameters: */ - - // Name of the transaction. Eg. "like", "download", etc. - // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) - String transactionName = "like"; - - // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". - String transactionType = "company_to_user"; - - // Some extra information about transaction. - // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) - String details = "lorem_ipsum"; - - HashMap metaProperty = new HashMap(); - metaProperty.put("name", transactionName); - metaProperty.put("type", transactionType); - metaProperty.put("details", details); - - - HashMap params = new HashMap(); - params.put("user_id", companyUserId); - params.put("to", payRuleAddress); - - params.put("meta_property", metaProperty); - params.put("raw_calldata", jsonRawCallData); - - JsonObject response = transactionsService.execute( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get Transaction Detail using userId and transactionId. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of end-user. - String userId = "ee8___"; - - // Unique identifier of the transaction to be retrieved. - String transactionId = "f1d___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("transaction_id", transactionId); - - JsonObject response = transactionsService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get User Transactions using userId. -Pagination is supported by this API. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of end-user. - String userId = "ee89___"; - - // Optional API parameters - - // Array of status values. - ArrayList statusesArray = new ArrayList(); - statusesArray.add("CREATED"); - statusesArray.add("SUBMITTED"); - statusesArray.add("SUCCESS"); - statusesArray.add("FAILED"); - - // To get transactions between a specific time interval, add start timestamp and end timestamp. - long startTime = 1563260786; - long endTime = 1563280786; - - // Name of the transaction. Eg. "like", "download", etc. - // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) - String transactionName = "like"; - - // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". - String transactionType = "company_to_user"; - - // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) - String details = "lorem_ipsum"; - - // Additional transaction information. There is no dependency between any of the metaProperty keys. - // However, if a key is present, its value cannot be null or undefined. - ArrayList> metaPropertyArray = new ArrayList>(); - HashMap metaPropertyArrayParams = new HashMap(); - metaPropertyArrayParams.put("name", transactionName); - metaPropertyArrayParams.put("type", transactionType); - metaPropertyArrayParams.put("details", details); - metaPropertyArray.add(metaPropertyArrayParams); - - Gson gsonObj = new Gson(); - String metaPropertyArrayJsonStr = gsonObj.toJson(metaPropertyArray); - - // Limit. - long limit = 10; - - // Pagination identifier from the previous API call response. Not needed for page one. - String paginationIdentifier = "eyJsY___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("start_time", startTime); - params.put("end_time", endTime); - params.put("statuses", statusesArray); - params.put("meta_properties", metaPropertyArrayJsonStr); - params.put("limit", limit); - params.put("pagination_identifier", paginationIdentifier); - - JsonObject response = transactionsService.getList( params ); - System.out.println("response: " + response.toString() ); ----- - -==== Balances Module - -* Initialize Balances service object to perform balances specific actions. -+ -[source,java] ----- - com.ost.services.Balance balancesService = services.balance; ----- - -* Get User Balance using userId. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId for whom balance needs to be fetched. - String userId = "c2c6___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - - JsonObject response = balancesService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Recovery Owners Module - -* Initialize Recovery Owners service object to perform recovery owners specific actions. -+ -[source,java] ----- - com.ost.services.RecoveryOwners recoveryOwnersService = services.recoveryOwners; ----- - -* Get Recovery Owner Detail using userId and recovery owner address. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId for whom recovery details needs to be fetched. - String userId = "c2c___"; - - // Recovery address of user. - String recoveryOwnerAddress = "0xe37___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("recovery_owner_address", recoveryOwnerAddress); - - JsonObject response = recoveryOwnersService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Tokens Module - -* Initialize Tokens service object to perform tokens specific actions. -+ -[source,java] ----- - com.ost.services.Tokens tokensService = services.tokens; ----- - -* Get Token Detail. -+ -[source,java] ----- - HashMap params = new HashMap(); - JsonObject response = tokensService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Chains Module - -* Initialize Chains service object to perform chains specific actions. -+ -[source,java] ----- - com.ost.services.Chains chainsService = services.chains; ----- - -* Get Chain Detail using chainId. -+ -[source,java] ----- - // Mandatory API parameters - - // ChainId for which details needs to be fetched. Only origin chainId and OST-specific auxiliary chainIds are allowed. - String chainId = "2000"; - - HashMap params = new HashMap(); - params.put("chain_id", chainId); - - JsonObject response = chainsService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Base Tokens Module - -* Initialize Base Tokens service object to perform base tokens specific actions. -+ -[source,java] ----- - com.ost.services.BaseTokens baseTokensService = services.baseTokens; ----- - -* Get Base Tokens Detail. -+ -[source,java] ----- - HashMap params = new HashMap(); - JsonObject response = baseTokensService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -=== Webhooks Module - -* Initialize Webhooks service object to perform webhooks specific actions. -+ -[source,java] ----- - com.ost.services.Webhooks webhooksService = services.webhooks; ----- - -* Create Webhook using the topics and the subscription url. -+ -[source,java] ----- - // Mandatory API parameters - - // Array of topics. - ArrayList topicParams = new ArrayList(); - topicParams.add("transactions/initiate"); - topicParams.add("transactions/success"); - - // URL where you want to receive the event notifications. - String url = "https://www.testingWebhooks.com"; - - // Optional API parameters - - // Status of a webhook. Possible values are "active" and "inactive". - String status = "active"; - - HashMap params = new HashMap(); - params.put("url", url); - params.put("status", status); - params.put("topics", topicParams); - - JsonObject response = webhooksService.create( params ); - System.out.println("response: " + response.toString() ); ----- - -* Update existing Webhook using a webhookId and an array of topics. -+ -[source,java] ----- - // Mandatory API parameters - - // Array of topics. - ArrayList topicParams = new ArrayList(); - topicParams.add("transactions/initiate"); - topicParams.add("transactions/success"); - - // Unique identifier for a webhook. - String webhookId = "a743___"; - - // Optional API parameters - - // Status of a webhook. Possible values are "active" and "inactive". - String status = "active"; - - HashMap params = new HashMap(); - params.put("webhook_id", webhookId); - params.put("status", status); - params.put("topics", topicParams); - - JsonObject response = webhooksService.update( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get Webhook using webhookId. -+ -[source,java] ----- - // Mandatory API parameters - - // Unique identifier for a webhook. - String webhookId = "a743___"; - - - HashMap params = new HashMap(); - params.put("webhook_id", webhookId); - - JsonObject response = webhooksService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get Webhook List. -Pagination is supported by this API. -+ -[source,java] ----- - // Mandatory API parameters - // No mandatory parameters. - - // Optional API parameters - - // Limit. - long limit = 10; - - // Pagination identifier from the previous API call response. Not needed for page one. - String paginationIdentifier = "eyJwY___"; - - HashMap params = new HashMap(); - params.put("limit", limit); - params.put("pagination_identifier", paginationIdentifier); - - JsonObject response = webhooksService.getList( params ); - System.out.println("response: " + response.toString() ); ----- - -* Delete Webhook using webhookId. -+ -[source,java] ----- - // Mandatory API parameters - - // Unique identifier for a webhook. - String webhookId = "a743___"; - - HashMap params = new HashMap(); - params.put("webhook_id", webhookId); - - JsonObject response = webhooksService.deleteWebhook( params ); - System.out.println("response: " + response.toString() ); ----- - -* Verify webhook request signature. -This can be used to validate if the webhook received at your end from OST platform is correctly signed. -+ -[source,java] ----- - // Webhook data obtained. - String webhookEventData = "{\"id\":\"54e3cd1c-afd7-4dcf-9c78-137c56a53582\",\"topic\":\"transactions/success\",\"created_at\":1560838772,\"webhook_id\":\"0823a4ea-5d87-44cf-8ca8-1e5a31bf8e46\",\"version\":\"v2\",\"data\":{\"result_type\":\"transaction\",\"transaction\":{\"id\":\"ddebe817-b94f-4b51-9227-f543fae4715a\",\"transaction_hash\":\"0x7ee737db22b58dc4da3f4ea4830ca709b388d84f31e77106cb79ee09fc6448f9\",\"from\":\"0x69a581096dbddf6d1e0fff7ebc1254bb7a2647c6\",\"to\":\"0xc2f0dde92f6f3a3cb13bfff43e2bd136f7dcfe47\",\"nonce\":3,\"value\":\"0\",\"gas_price\":\"1000000000\",\"gas_used\":120558,\"transaction_fee\":\"120558000000000\",\"block_confirmation\":24,\"status\":\"SUCCESS\",\"updated_timestamp\":1560838699,\"block_timestamp\":1560838698,\"block_number\":1554246,\"rule_name\":\"Pricer\",\"meta_property\":{},\"transfers\":[{\"from\":\"0xc2f0dde92f6f3a3cb13bfff43e2bd136f7dcfe47\",\"from_user_id\":\"acfdea7d-278e-4ffc-aacb-4a21398a280c\",\"to\":\"0x0a754aaab96d634337aac6556312de396a0ca46a\",\"to_user_id\":\"7bc8e0bd-6761-4604-8f8e-e33f86f81309\",\"amount\":\"112325386\",\"kind\":\"transfer\"}]}}}"; - - // Get webhoook version from webhook events data. - String version = "v2"; - - // Get ost-timestamp from the response received in event. - String requestTimestamp = "1559902637"; - - // Get signature from the response received in event. - String signature = "2c56c143550c603a6ff47054803f03ee4755c9c707986ae27f7ca1dd1c92a824"; - - String webhookSecret = "mySecret"; - String stringifiedData = webhookEventData; - - Boolean response = webhooksService.verifySignature( version, stringifiedData, requestTimestamp, signature, webhookSecret ); - System.out.println("response: " + response ); ----- - -=== Redemption Modules - -Two modules of redemption, "Redeemable SKUs" and "User Redemptions", are described below. - -==== Redeemable SKUs Module - -* Initialize Redeemable SKUs service object to perform redeemable skus specific actions. -+ -[source,java] ----- - com.ost.services.RedeemableSkus redeemableSkusService = services.redeemableSkus; ----- - -* Get Redeemable SKU detail using the redeemable sku id. -+ -[source,java] ----- - // Mandatory API parameters - - // Fetch details of following redeemable sku. - String redeemableSkuId = 'c2c__'; - - HashMap params = new HashMap(); - params.put("redeemable_sku_id", redeemableSkuId); - - JsonObject response = redeemableSkusService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get Redeemable SKUs List. -Pagination is supported by this API. -+ -[source,java] ----- - // Mandatory API parameters - // NOTE: No mandatory parameters. - - // Optional API parameters - - // Limit. - long limit = 10; - - // Array of redeemable SKU ids. - ArrayList redemptionSkuIdsArray = new ArrayList(); - redemptionSkuIdsArray.add("1001"); - redemptionSkuIdsArray.add("1002"); - - // Pagination identifier from the previous API call response. Not needed for page one. - String paginationIdentifier = "eyJ___"; - - HashMap params = new HashMap(); - params.put("redemption_ids", redemptionSkuIdsArray); - params.put("pagination_identifier", paginationIdentifier); - params.put("limit", limit); - - JsonObject response = redeemableSkusService.getList( params ); - System.out.println("response: " + response.toString() ); ----- -+ -==== User Redemptions Module - -* Initialize Redemptions service object to perform user redemption specific actions. -+ -[source,java] ----- - com.ost.services.Redemptions redemptionsService = services.redemptions; ----- - -* Get User redemption details using the userId and redemptionId. -+ -[source,java] ----- - // Mandatory API parameters - - // UserId of user for whom redemption details needs to be fetched. - String userId = "c2c6___"; - - // Unique identifier of the redemption of user. - String redemptionId = "c2c___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("redemption_id", redemptionId); - - JsonObject response = redemptionsService.get( params ); - System.out.println("response: " + response.toString() ); ----- - -* Get User Redemptions List. -Pagination is supported by this API. -+ -[source,java] ----- - // Mandatory API parameters - String userId = "c2c6___"; - - // Optional API parameters - - // Limit. - long limit = 10; - - // Array of user redemption uuids. - ArrayList redemptionIdsArray = new ArrayList(); - redemptionIdsArray.add("eyJ___"); - redemptionIdsArray.add("eyJ___"); - - // Pagination identifier from the previous API call response. Not needed for page one. - String paginationIdentifier = "eyJ___"; - - HashMap params = new HashMap(); - params.put("user_id", userId); - params.put("redemption_ids", redemptionIdsArray); - params.put("pagination_identifier", paginationIdentifier); - params.put("limit", limit); - - JsonObject response = redemptionsService.getList( params ); - System.out.println("response: " + response.toString() ); ----- diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc index c02665a..86b3425 100644 --- a/docs/modules/ROOT/pages/index.adoc +++ b/docs/modules/ROOT/pages/index.adoc @@ -1,3 +1,1026 @@ -This is the index.adoc page for OST-SDK-JAVA += OST Server-Side Java SDK -This is a test :) \ No newline at end of file +image::https://travis-ci.org/ostdotcom/ost-sdk-java.svg?branch=develop[Build Status,link=https://travis-ci.org/ostdotcom/ost-sdk-java] + +https://dev.ost.com/[OST] Platform SDK for Java. + +== Introduction + +OST is a complete technology solution enabling mainstream businesses to easily launch blockchain based economies without requiring blockchain development. + +Brand Tokens (BTs) are white-label cryptocurrency tokens with utility representations running on highly-scalable Ethereum-based utility blockchains, backed by value token (such as OST, USDC) staked on Ethereum mainnet. +Within a business`s token economy, BTs can only be transferred to whitelisted user addresses. +This ensures that they stay within the token economy. + +The OST technology stack is designed to give businesses everything they need to integrate, test, and deploy BTs. +Within the OST suite of products, developers can use OST Platform to create, test, and launch Brand Tokens. + +OST APIs and server-side SDKs make it simple and easy for developers to integrate blockchain tokens into their apps. + +For documentation, visit https://dev.ost.com/ + +== Getting Started + +=== Setup Brand Token + +. Sign-up on https://platform.ost.com[OST Platform] and setup your Brand Token. +. Obtain your API Key and API Secret from https://platform.ost.com/mainnet/developer[developers page]. + +=== Installation + +==== Maven users + +Add this dependency to your project's POM + +[source,xml] +---- + + com.ost + ost-sdk-java + 2.2.1 + +---- + +==== Building from source using Maven + +Clone the repository: + +[source,bash] +---- +git clone https://github.com/ostdotcom/ost-sdk-java.git +cd ost-sdk-java +---- + +Package using MVN (without dependencies): + +[source,bash] +---- +mvn clean package -DskipTests +---- + +Package using MVN (with dependencies): + +[source,bash] +---- +mvn clean compile assembly:single -DskipTests +---- + +The jar file can be found in the target folder. + +== Usage + +* Initialize the SDK object: ++ +[source,java] +---- + // Declare connection parameters. + + // Mandatory API parameters + + String apiKey = "__abc"; // OBTAINED FROM DEVELOPER PAGE + String apiSecret = "_xyz"; // OBTAINED FROM DEVELOPER PAGE + + /* + The valid API endpoints are: + 1. Mainnet: "https://api.ost.com/mainnet/v2/" + 2. Testnet: "https://api.ost.com/testnet/v2/" + */ + + String apiEndPoint = "https://api.ost.com/testnet/v2/"; + + HashMap sdkConfig = new HashMap(); + sdkConfig.put("apiEndpoint", apiEndPoint); + sdkConfig.put("apiKey", apiKey); + sdkConfig.put("apiSecret", apiSecret); + + // Optional API parameters + + // This is the timeout in seconds for which the socket connection will remain open. + long timeoutInSeconds = 60; // The value of timeout will always be of type long. + + HashMap nestedparam = new HashMap(); + + nestedparam.put("timeout", timeoutInSeconds); + sdkConfig.put("config", nestedparam); + + // OST server side sdk object. + OSTSDK ostObj = new OSTSDK(sdkConfig); + com.ost.services.Manifest services = (com.ost.services.Manifest) ostObj.services; +---- + +=== Users Module + +* Initialize Users service object to perform user specific actions. ++ +[source,java] +---- + com.ost.services.Users usersService = services.users; +---- + +* Create User. +This creates a unique identifier for each user. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = usersService.create( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Detail using the userId obtained in user create. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom user details needs to be fetched. + String userId = "c2c__"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + JsonObject response = usersService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Users List. +Pagination is supported in this API. ++ +[source,java] +---- + // Mandatory API parameters + // No mandatory parameters. + + // Optional API parameters + + // Array of userIds for which data needs to be fetched. + ArrayList userIdsArray = new ArrayList(); + userIdsArray.add("c2c__"); + userIdsArray.add("d2c__"); + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "e77y___"; + + // Limit. + long limit = 10; + + HashMap params = new HashMap(); + params.put("ids", userIdsArray); + params.put("limit", limit); + params.put("pagination_identifier", paginationIdentifier); + + JsonObject response = usersService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Devices Module + +* Initialize Devices service object to perform device specific actions. ++ +[source,java] +---- + com.ost.services.Devices devicesService = services.devices; +---- + +* Create a Device for User. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device needs to be created. + String userId = "c2c___"; + + // Device address of user's device. + String deviceAddress = "0x1Ea___"; + + // Device API signer address. + String apiSignerAddress = "0x5F8___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("address", deviceAddress); + params.put("api_signer_address", apiSignerAddress); + + JsonObject response = devicesService.create( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Device Detail using userId and deviceAddress. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device details needs to be fetched. + String userId = "c2c___"; + + // Device address of user's device. + String deviceAddress = "0x1E___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("device_address", deviceAddress); + + JsonObject response = devicesService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Devices List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device details needs to be fetched. + String userId = "c2c6___"; + + // Optional API parameters + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJ___"; + + // Array of device addresses of end user. + ArrayList deviceAddressesArray = new ArrayList(); + deviceAddressesArray.add("0x59___"); + deviceAddressesArray.add("0xab___"); + + // Limit. + long limit = 10; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("addresses", deviceAddressesArray); + params.put("pagination_identifier", paginationIdentifier); + params.put("limit", limit); + + JsonObject response = devicesService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Device Managers Module + +* Initialize Device Manager service object to perform device manager specific actions. ++ +[source,java] +---- + com.ost.services.DeviceManagers deviceManagersService = services.deviceManagers; +---- + +* Get Device Manager Detail using userId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom device manager details needs to be fetched. + String userId = "c2c___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + + JsonObject response = deviceManagersService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Sessions Module + +* Initialize Sessions service object to perform session specific actions. ++ +[source,java] +---- + com.ost.services.Sessions sessionsService = services.sessions; +---- + +* Get User Session Detail using userId and session address. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom session details needs to be fetched. + String userId = "c2c___"; + + // Session address of user for which details needs to be fetched. + String sessionAddress = "0x1Ea___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("session_address", sessionAddress); + + JsonObject response = sessionsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Sessions List using userId. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom session details needs to be fetched. + String userId = "c2c___"; + + // Optional API parameters: + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJs___"; + + // Array of session addresses of end user. + ArrayList sessionAddressesArray = new ArrayList(); + sessionAddressesArray.add("0x59___"); + sessionAddressesArray.add("0xab___"); + + // Limit. + long limit = 10; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("pagination_identifier", paginationIdentifier); + params.put("addresses", sessionAddressesArray); + params.put("limit", limit); + + JsonObject response = sessionsService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Executing Transactions + +For executing transactions, you need to understand the 4 modules described below. + +==== Rules Module + +* Initialize Rules service object to perform rules specific actions. ++ +[source,java] +---- + com.ost.services.Rules rulesService = services.rules; +---- + +* List Rules. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = rulesService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +==== Price Points Module + +* Initialize Price Points service object to perform price points specific actions. ++ +[source,java] +---- + com.ost.services.PricePoints pricePointsService = services.pricePoints; +---- + +* Get Price Points Detail. ++ +[source,java] +---- + // Mandatory API parameters + + // ChainId of your brand token economy. + long chainId = 2000; + + HashMap params = new HashMap(); + params.put("chain_id", chainId); + + JsonObject response = pricePointsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +==== Transactions Module + +* Initialize Transactions service object to perform transaction specific actions. ++ +[source,java] +---- + com.ost.services.Transactions transactionsService = services.transactions; +---- + +* DIRECT-TRANSFERS execute transaction should be used to transfer BTs to your end-users. ++ +[source,java] +---- + // Mandatory API parameters + + // Token holder address of receiver. + String transferToAddress = "0xa3___"; + + // Amount of tokens to be transferred. + String transferAmount = "1"; + + // Company userId. + String companyUserId = "ee89___"; + + // Address of DirectTransfer rule. Use list rules API of Rules module to get the address of rules. + // In the rules array which you will get in response, use the address having name "Direct Transfer". + String directTransferRuleAddress = "0xe379___"; + + // Parameters required for rule execution. + ArrayList arrayListForReceiverTokenHolderAddress = new ArrayList(); + arrayListForReceiverTokenHolderAddress.add(transferToAddress); + + ArrayList arrayListAmount = new ArrayList(); + arrayListAmount.add(transferAmount); + + ArrayList nestedArraylist = new ArrayList(); + nestedArraylist.add(arrayListForReceiverTokenHolderAddress); + nestedArraylist.add(arrayListAmount); + + // Parameters required for rule execution. + HashMap nestedparams = new HashMap(); + nestedparams.put("method", "directTransfers"); // Rule name which needs to be passed as-is. + nestedparams.put("parameters", nestedArraylist); + + Gson gsonObj = new Gson(); + String jsonStr = gsonObj.toJson(nestedparams); + + + HashMap params = new HashMap(); + + params.put("user_id", companyUserId); + params.put("to", directTransferRuleAddress); + params.put("raw_calldata", jsonStr); + + // Optional API parameters + + // Name of the transaction. Eg. "like", "download", etc. + // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) + String transactionName = "like"; + + // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". + String transactionType = "company_to_user"; + + // Some extra information about transaction. + // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) + String details = "lorem_ipsum"; + + // Additional transaction information. There is no dependency between any of the metaProperty keys. + // However, if a key is present, its value cannot be null or undefined. + HashMap metaProperty = new HashMap(); + metaProperty.put("name", transactionName); + metaProperty.put("type", transactionType); + metaProperty.put("details", details); + + params.put("meta_property", metaProperty); + + JsonObject response = transactionsService.execute( params ); + System.out.println("response: " + response.toString() ); +---- + +* PAY Execute Transaction should be used when transactions of BTs equivalent to some fiat amount need to be executed. ++ +[source,java] +---- + // Mandatory API parameters + + // Token holder address of receiver. + String transferToAddress = "0xa31__"; + + // Company token holder address. + String companyTokenHolderAddress = "0xa963___"; + + + // Pay currency code. Supported currency codes are "USD", "EUR" and "GBP". + String payCurrencyCode = "USD"; + + // In pay transaction, the transfer amounts are in pay currency (fiat currency like USD) which then are converted + // into tokens. Use get price point detail API of Price Points module to get this value. + double pricePoint = 0.020606673; + + // Price point needs to be passed in atto. Multiply the price point with 10^18. Also, this value should be a string. + BigDecimal intendedPricePointBD = new BigDecimal(pricePoint).multiply((new BigDecimal(10)).pow(18)); + String intendedPricePointInAtto = intendedPricePointBD.toString().split("\\.")[0]; + + // Amount of Fiat to be transferred. + double transferAmountInFiat = 0.1; + + // Transfer amount in wei needs to be passed in atto. Multiply the fiat transfer amount with 10^18. Also, this value should be a string. + BigDecimal fiatTransferAmountInWeiBD = new BigDecimal(transferAmountInFiat).multiply((new BigDecimal(10)).pow(18)); + String fiatTransferAmountInAtto = fiatTransferAmountInWeiBD.toString().split("\\.")[0]; + + // Parameters required for rule execution. + ArrayList arrayListForReceiverTokenHolderAddress = new ArrayList(); + arrayListForReceiverTokenHolderAddress.add(transferToAddress); + + ArrayList arrayListAmount = new ArrayList(); + arrayListAmount.add(fiatTransferAmountInAtto); + Gson gsonObj = new Gson(); + + ArrayList nestedArraylist = new ArrayList(); + nestedArraylist.add(companyTokenHolderAddress); + nestedArraylist.add(arrayListForReceiverTokenHolderAddress); + nestedArraylist.add(arrayListAmount); + nestedArraylist.add(payCurrencyCode); + nestedArraylist.add(intendedPricePointInAtto); + + HashMap nestedparams = new HashMap(); + nestedparams.put("method", "pay"); // Rule name which needs to be passed as-is. + nestedparams.put("parameters", nestedArraylist); + + String jsonRawCallData = gsonObj.toJson(nestedparams); + + // Company userId. + String companyUserId = "ee8___"; + + // Address of Pay rule. Use list rules API to get the address of rules. + // In the rules array which you will get in response, use the address having name "Pricer". + String payRuleAddress = "0xe37___"; + + /* Optional API parameters: */ + + // Name of the transaction. Eg. "like", "download", etc. + // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) + String transactionName = "like"; + + // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". + String transactionType = "company_to_user"; + + // Some extra information about transaction. + // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) + String details = "lorem_ipsum"; + + HashMap metaProperty = new HashMap(); + metaProperty.put("name", transactionName); + metaProperty.put("type", transactionType); + metaProperty.put("details", details); + + + HashMap params = new HashMap(); + params.put("user_id", companyUserId); + params.put("to", payRuleAddress); + + params.put("meta_property", metaProperty); + params.put("raw_calldata", jsonRawCallData); + + JsonObject response = transactionsService.execute( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Transaction Detail using userId and transactionId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of end-user. + String userId = "ee8___"; + + // Unique identifier of the transaction to be retrieved. + String transactionId = "f1d___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("transaction_id", transactionId); + + JsonObject response = transactionsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Transactions using userId. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of end-user. + String userId = "ee89___"; + + // Optional API parameters + + // Array of status values. + ArrayList statusesArray = new ArrayList(); + statusesArray.add("CREATED"); + statusesArray.add("SUBMITTED"); + statusesArray.add("SUCCESS"); + statusesArray.add("FAILED"); + + // To get transactions between a specific time interval, add start timestamp and end timestamp. + long startTime = 1563260786; + long endTime = 1563280786; + + // Name of the transaction. Eg. "like", "download", etc. + // NOTE: Max length 25 characters (Allowed characters: [A-Za-z0-9_/s]) + String transactionName = "like"; + + // Transaction type. Possible values: "company_to_user", "user_to_user", "user_to_company". + String transactionType = "company_to_user"; + + // NOTE: Max length 125 characters (Allowed characters: [A-Za-z0-9_/s]) + String details = "lorem_ipsum"; + + // Additional transaction information. There is no dependency between any of the metaProperty keys. + // However, if a key is present, its value cannot be null or undefined. + ArrayList> metaPropertyArray = new ArrayList>(); + HashMap metaPropertyArrayParams = new HashMap(); + metaPropertyArrayParams.put("name", transactionName); + metaPropertyArrayParams.put("type", transactionType); + metaPropertyArrayParams.put("details", details); + metaPropertyArray.add(metaPropertyArrayParams); + + Gson gsonObj = new Gson(); + String metaPropertyArrayJsonStr = gsonObj.toJson(metaPropertyArray); + + // Limit. + long limit = 10; + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJsY___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("start_time", startTime); + params.put("end_time", endTime); + params.put("statuses", statusesArray); + params.put("meta_properties", metaPropertyArrayJsonStr); + params.put("limit", limit); + params.put("pagination_identifier", paginationIdentifier); + + JsonObject response = transactionsService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +==== Balances Module + +* Initialize Balances service object to perform balances specific actions. ++ +[source,java] +---- + com.ost.services.Balance balancesService = services.balance; +---- + +* Get User Balance using userId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId for whom balance needs to be fetched. + String userId = "c2c6___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + + JsonObject response = balancesService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Recovery Owners Module + +* Initialize Recovery Owners service object to perform recovery owners specific actions. ++ +[source,java] +---- + com.ost.services.RecoveryOwners recoveryOwnersService = services.recoveryOwners; +---- + +* Get Recovery Owner Detail using userId and recovery owner address. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId for whom recovery details needs to be fetched. + String userId = "c2c___"; + + // Recovery address of user. + String recoveryOwnerAddress = "0xe37___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("recovery_owner_address", recoveryOwnerAddress); + + JsonObject response = recoveryOwnersService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Tokens Module + +* Initialize Tokens service object to perform tokens specific actions. ++ +[source,java] +---- + com.ost.services.Tokens tokensService = services.tokens; +---- + +* Get Token Detail. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = tokensService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Chains Module + +* Initialize Chains service object to perform chains specific actions. ++ +[source,java] +---- + com.ost.services.Chains chainsService = services.chains; +---- + +* Get Chain Detail using chainId. ++ +[source,java] +---- + // Mandatory API parameters + + // ChainId for which details needs to be fetched. Only origin chainId and OST-specific auxiliary chainIds are allowed. + String chainId = "2000"; + + HashMap params = new HashMap(); + params.put("chain_id", chainId); + + JsonObject response = chainsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Base Tokens Module + +* Initialize Base Tokens service object to perform base tokens specific actions. ++ +[source,java] +---- + com.ost.services.BaseTokens baseTokensService = services.baseTokens; +---- + +* Get Base Tokens Detail. ++ +[source,java] +---- + HashMap params = new HashMap(); + JsonObject response = baseTokensService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +=== Webhooks Module + +* Initialize Webhooks service object to perform webhooks specific actions. ++ +[source,java] +---- + com.ost.services.Webhooks webhooksService = services.webhooks; +---- + +* Create Webhook using the topics and the subscription url. ++ +[source,java] +---- + // Mandatory API parameters + + // Array of topics. + ArrayList topicParams = new ArrayList(); + topicParams.add("transactions/initiate"); + topicParams.add("transactions/success"); + + // URL where you want to receive the event notifications. + String url = "https://www.testingWebhooks.com"; + + // Optional API parameters + + // Status of a webhook. Possible values are "active" and "inactive". + String status = "active"; + + HashMap params = new HashMap(); + params.put("url", url); + params.put("status", status); + params.put("topics", topicParams); + + JsonObject response = webhooksService.create( params ); + System.out.println("response: " + response.toString() ); +---- + +* Update existing Webhook using a webhookId and an array of topics. ++ +[source,java] +---- + // Mandatory API parameters + + // Array of topics. + ArrayList topicParams = new ArrayList(); + topicParams.add("transactions/initiate"); + topicParams.add("transactions/success"); + + // Unique identifier for a webhook. + String webhookId = "a743___"; + + // Optional API parameters + + // Status of a webhook. Possible values are "active" and "inactive". + String status = "active"; + + HashMap params = new HashMap(); + params.put("webhook_id", webhookId); + params.put("status", status); + params.put("topics", topicParams); + + JsonObject response = webhooksService.update( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Webhook using webhookId. ++ +[source,java] +---- + // Mandatory API parameters + + // Unique identifier for a webhook. + String webhookId = "a743___"; + + + HashMap params = new HashMap(); + params.put("webhook_id", webhookId); + + JsonObject response = webhooksService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Webhook List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + // No mandatory parameters. + + // Optional API parameters + + // Limit. + long limit = 10; + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJwY___"; + + HashMap params = new HashMap(); + params.put("limit", limit); + params.put("pagination_identifier", paginationIdentifier); + + JsonObject response = webhooksService.getList( params ); + System.out.println("response: " + response.toString() ); +---- + +* Delete Webhook using webhookId. ++ +[source,java] +---- + // Mandatory API parameters + + // Unique identifier for a webhook. + String webhookId = "a743___"; + + HashMap params = new HashMap(); + params.put("webhook_id", webhookId); + + JsonObject response = webhooksService.deleteWebhook( params ); + System.out.println("response: " + response.toString() ); +---- + +* Verify webhook request signature. +This can be used to validate if the webhook received at your end from OST platform is correctly signed. ++ +[source,java] +---- + // Webhook data obtained. + String webhookEventData = "{\"id\":\"54e3cd1c-afd7-4dcf-9c78-137c56a53582\",\"topic\":\"transactions/success\",\"created_at\":1560838772,\"webhook_id\":\"0823a4ea-5d87-44cf-8ca8-1e5a31bf8e46\",\"version\":\"v2\",\"data\":{\"result_type\":\"transaction\",\"transaction\":{\"id\":\"ddebe817-b94f-4b51-9227-f543fae4715a\",\"transaction_hash\":\"0x7ee737db22b58dc4da3f4ea4830ca709b388d84f31e77106cb79ee09fc6448f9\",\"from\":\"0x69a581096dbddf6d1e0fff7ebc1254bb7a2647c6\",\"to\":\"0xc2f0dde92f6f3a3cb13bfff43e2bd136f7dcfe47\",\"nonce\":3,\"value\":\"0\",\"gas_price\":\"1000000000\",\"gas_used\":120558,\"transaction_fee\":\"120558000000000\",\"block_confirmation\":24,\"status\":\"SUCCESS\",\"updated_timestamp\":1560838699,\"block_timestamp\":1560838698,\"block_number\":1554246,\"rule_name\":\"Pricer\",\"meta_property\":{},\"transfers\":[{\"from\":\"0xc2f0dde92f6f3a3cb13bfff43e2bd136f7dcfe47\",\"from_user_id\":\"acfdea7d-278e-4ffc-aacb-4a21398a280c\",\"to\":\"0x0a754aaab96d634337aac6556312de396a0ca46a\",\"to_user_id\":\"7bc8e0bd-6761-4604-8f8e-e33f86f81309\",\"amount\":\"112325386\",\"kind\":\"transfer\"}]}}}"; + + // Get webhoook version from webhook events data. + String version = "v2"; + + // Get ost-timestamp from the response received in event. + String requestTimestamp = "1559902637"; + + // Get signature from the response received in event. + String signature = "2c56c143550c603a6ff47054803f03ee4755c9c707986ae27f7ca1dd1c92a824"; + + String webhookSecret = "mySecret"; + String stringifiedData = webhookEventData; + + Boolean response = webhooksService.verifySignature( version, stringifiedData, requestTimestamp, signature, webhookSecret ); + System.out.println("response: " + response ); +---- + +=== Redemption Modules + +Two modules of redemption, "Redeemable SKUs" and "User Redemptions", are described below. + +==== Redeemable SKUs Module + +* Initialize Redeemable SKUs service object to perform redeemable skus specific actions. ++ +[source,java] +---- + com.ost.services.RedeemableSkus redeemableSkusService = services.redeemableSkus; +---- + +* Get Redeemable SKU detail using the redeemable sku id. ++ +[source,java] +---- + // Mandatory API parameters + + // Fetch details of following redeemable sku. + String redeemableSkuId = 'c2c__'; + + HashMap params = new HashMap(); + params.put("redeemable_sku_id", redeemableSkuId); + + JsonObject response = redeemableSkusService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get Redeemable SKUs List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + // NOTE: No mandatory parameters. + + // Optional API parameters + + // Limit. + long limit = 10; + + // Array of redeemable SKU ids. + ArrayList redemptionSkuIdsArray = new ArrayList(); + redemptionSkuIdsArray.add("1001"); + redemptionSkuIdsArray.add("1002"); + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJ___"; + + HashMap params = new HashMap(); + params.put("redemption_ids", redemptionSkuIdsArray); + params.put("pagination_identifier", paginationIdentifier); + params.put("limit", limit); + + JsonObject response = redeemableSkusService.getList( params ); + System.out.println("response: " + response.toString() ); +---- ++ +==== User Redemptions Module + +* Initialize Redemptions service object to perform user redemption specific actions. ++ +[source,java] +---- + com.ost.services.Redemptions redemptionsService = services.redemptions; +---- + +* Get User redemption details using the userId and redemptionId. ++ +[source,java] +---- + // Mandatory API parameters + + // UserId of user for whom redemption details needs to be fetched. + String userId = "c2c6___"; + + // Unique identifier of the redemption of user. + String redemptionId = "c2c___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("redemption_id", redemptionId); + + JsonObject response = redemptionsService.get( params ); + System.out.println("response: " + response.toString() ); +---- + +* Get User Redemptions List. +Pagination is supported by this API. ++ +[source,java] +---- + // Mandatory API parameters + String userId = "c2c6___"; + + // Optional API parameters + + // Limit. + long limit = 10; + + // Array of user redemption uuids. + ArrayList redemptionIdsArray = new ArrayList(); + redemptionIdsArray.add("eyJ___"); + redemptionIdsArray.add("eyJ___"); + + // Pagination identifier from the previous API call response. Not needed for page one. + String paginationIdentifier = "eyJ___"; + + HashMap params = new HashMap(); + params.put("user_id", userId); + params.put("redemption_ids", redemptionIdsArray); + params.put("pagination_identifier", paginationIdentifier); + params.put("limit", limit); + + JsonObject response = redemptionsService.getList( params ); + System.out.println("response: " + response.toString() ); +----