Integrate via SDK

To request the SDK, contact the Ripple support team.

The SDK is provided as a Maven dependency and can be added to a JVM project.

The SDK doesn't implement a signer service, which directly depends on the key management system used by the service consumer. You first need to implement this signer service as a Java class before using the SDK. For more information, see Implement the signer service.

An example signer implementation is available upon request from the Ripple support team.

Prerequisites

To use the SDK, you need access to a working instance of Ripple Custody.

Install the SDK

To install the SDK, run the following command:

mvn install:install-file -Dfile=./sdk-{sdk-version}.jar -DgroupId=com.metaco -DartifactId=sdk -Dversion={sdk-version} -Dpackaging=jar -DpomFile=./sdk-{sdk-version}.xml

When the Java project is created, configure the SDK dependency project for Maven use by adding a dependency in the following format:

<dependencies>
    <dependency>
        <groupId>com.metaco</groupId>
        <articatId>sdk</artifactId>
        <version>{sdk-version}</version>
    </dependency>
</dependencies>

The version number must match the SDK package.

Implement the signer service

The SDK does not natively implement methods to manage user keys and perform signatures. This choice is made for security reasons, so that the SDK code does not have direct access to private keys. This means that you must create your own key pair and signature handling logic.

The signer interface is the interface that the SDK uses to communicate with user key and signer implementation. This is passed to the SDK when a HarmonizeContext instance is loaded, as follows:

var harmonizeCtx = HarmonizeContext.load(signer);
// we get the Ripple Custody instance from the context
var harmonize = harmonizeCtx.harmonize;

You can switch in a new signer, for example for a new user instance, with the following command:

var newHarmonizeCtx = harmonizeCtz.switchSigner(newSigner);

You can request an example test signer template from the Ripple support team.

The signer implementation is SDK user-specific. To implement the signer, use the provided Signer interface.

JSON message serialization

Before a message is signed, you need to ensure it is converted to canonical JSON format. This ensures that hashes are repeatable from the JSON encoded data. The Ripple Custody API performs the same operation before checking the hash.

All entities returned and used by the SDK implement the .toJson() method, which produces the correctly canonicalized JSON output, in the appropriate format for the user to apply the signature. You can optionally use the GsonUtils helper class to serialize any messages for correct signing.

Configure the SDK

You can load the configuration from the file system or set it with environment variables. The SDK searches for a configuration in the following order:

A harmonize.json file in the home directory.
A harmonize.json file in the directory of command execution.
A user-provided configuration file, via the --conf flag.
A file specified using the environment variable HARMONIZE_CONF.
Direct environment variables.

You can overwrite any configuration variable with an environment variable.

The configuration variables are listed in the following table:

Name	Description	Required
`GATEWAY_URL`	URL that points to the API gateway	Yes
`OAUTH_URL`	URL that points to the OAuth token service	Yes
`OAUTH_CLIENT_ID`	OAuth client ID	Yes
`OAUTH_CLIENT_SECRET`	OAuth client secret	Yes
`TIMEOUT`	HTTP timeout	No
`HTTP_VERSION`	HTTP version to use	No
`USER_ID`	User ID to use for performing SDK operations	Yes
`OPEN_API_VALIDATE_WARN_ONLY`	Whether to use API validation. If `true`, API validation is turned off. Default is `false`.	No
`OPEN_API_VALIDATE_STRICT_ENUMS`	Whether to use ENUM validation. If `true`, API ENUM validation is turned off. Default is `false`.	No

JSON example

The following example shows a JSON configuration file:

{
  "GATEWAY_URL": "<>",
  "OAUTH_URL": "<>",
  "OAUTH_CLIENT_ID": "<>",
  "OAUTH_CLIENT_SECRET": "<>",
  "TIMEOUT": "<>",
  "HTTP_VERSION": "<>",
  "USER_ID": "<The user id>",
  "OPEN_API_VALIDATE_WARN_ONLY": "boolean",
  "OPEN_API_VALIDATE_STRICT_ENUMS": "boolean"
}