Xpring SDK

Getting Started With Xpring SDK

This tutorial familiarizes you with Xpring SDK. Xpring SDK provides tools so that you can readily develop apps on Xpring Platform, and thus send and receive value within your apps. For more information about the design and architecture of Xpring SDK, see What is Xpring and the Xpring SDK?.

Xpring SDK is currently available for JavaScript, Java, and Swift.

Install the Xpring SDK library

Follow the corresponding instructions for your preferred language.

JavaScript

Install the Xpring-JS package using npm:

$ npm i xpring-js
Java

If you are using Maven, then in your Java project, add the following lines to your pom.xml file in the dependencies object:

<dependency>
  <groupId>io.xpring</groupId>
  <artifactId>xpring4j</artifactId>
  <version>1.0.0</version>
</dependency>


If you are using Gradle, then in your Java project, add the following line to your dependencies section in your build.gradle file:

io.xpring:xpring4j:1.20
Swift

You can use either Carthage or CocoaPods to install Xpring SDK for Swift.

To install via Carthage, add the following line to your Cartfile.

github "xpring-eng/XpringKit"


To install via CocoaPods, add the following line to your Podfile.

pod 'XpringKit'

Obtain credentials for the XRP Ledger Testnet

The XRP Ledger is available on both Mainnet and Testnet. Testnet disburses tokens that have no value, but otherwise functions in an nearly equivalent manner to Mainnet. These tokens are referred to as "test XRP." See XRP Ledger Parallel Networks.

Generate your credentials for Testnet at Xpring Portal. Save these credentials for use when generating a wallet programmatically. This wallet will be loaded with the test equivalent of 1000 XRP, so you can experiment with sending and receiving value on Testnet.

You can also generate Testnet credentials with XRP Faucets. You can generate multiple sets of credentials, and use these to test sending and receiving value between different addresses.

You are now ready to build a simple app.

Build a Simple App

You can build a simple JavaScript app that:

  1. Generates a wallet
  2. Connects to Xpring server
  3. Checks balances
  4. Sends test XRP

The following sections provide JavaScript code snippets that demonstrate these Xpring SDK capabilities.

Generate wallet

Build a wallet using the seed (Secret) from the Testnet credentials that you previously obtained.

const { Wallet } = require("xpring-js");
const seedWallet = Wallet.generateWalletFromSeed("ssZYH1B6yhcAHwRRNRTS1sqCMs7Pb");

Tip: Xpring SDK also supports Hierarchical Deterministic (HD) Wallets.

Connect to server

To check balances and send test XRP, your app must connect to the Xpring-hosted server that is connected to the XRP Ledger. You can reach this endpoint at grpc.xpring.tech:80.

const { Wallet, XpringClient } = require("xpring-js");
const seedWallet = Wallet.generateWalletFromSeed("ssZYH1B6yhcAHwRRNRTS1sqCMs7Pb");
const remoteURL = "grpc.xpring.tech:80";
const xpringClient = new XpringClient(remoteURL);
Check balances

Before sending test XRP, you should check your balance.

const testNetAddress = seedWallet.getAddress();
const balance = await xpringClient.getBalance(testNetAddress);
Send test XRP

To send test XRP, you use the wallet you have created, the amount you have specified, and the recipient address you have specified.

const amount = BigInt("10");
const recipientAddress = "X7u4MQVhU2YxS4P9fWzQjnNuDRUkP3GM6kiVjTjcQgUU3Jr";
const result = await xpringClient.send(amount, recipientAddress, seedWallet)

More examples

For more examples, see the Xpring-JS repository on GitHub.

What is Xpring and Xpring SDK?

Xpring is a solution for developers who want straightforward access to the capabilities of the XRP Ledger, regardless of their knowledge of, or comfort with, cryptography and distributed systems. You can build apps using your preferred language. With Xpring, your app can be used to transact value around the world, regardless of payment size, borders, or the platform you use to build your app.

Xpring SDK delivers the most common features of the XRP ecosystem in an easy to use package. Xpring SDK is the foundation for the Xpring developer site and will also power future Xpring services.

With the Xpring SDK, the following capabilities are supported:

  • Check an account balance
  • Make XRP payments
  • Determine transaction status

Transaction history support is coming soon.

Xpring SDK supports these capabilities across the following languages:

  • Java
  • Swift
  • NodeJS (with browser-based support arriving soon)

All of these features use a common code base, which ensures that Xpring delivers features across all supported languages simultaneously. In practice, this means that an iOS engineer who is integrating the Xpring SDK into their app can explain how to use the APIs to their peer Android engineer.

Architecture

Xpring SDK achieves cross-platform consistency with pragmatic code reuse. At a high level, you can break most multi-platform SDKs, including the Xpring SDK, into three components:

  • Networking and Remote Procedure Calls (RPCs)
  • Common core functionality
  • A public API that connects these features together in an idiomatic API
Networking

Any client-side library needs a reliable way to communicate with a remote service. In the case of Xpring SDK, a client-side library connects to a remote XRP Ledger node which serves data about the state of the XRP Ledger across the distributed system.

Without Xpring SDK, each XRP Ledger server uses a JSON API to communicate and interact with the node. This API has no preconfigured bindings in any language, requiring developers of client libraries to interact with the node by hand-rolling their own untyped JSON objects in their language of choice.

Xpring uses gRPC, which is a cross-platform technology used to define an API using a lightweight markup language. The markup language is then “compiled” to generate code in a number of native languages. The generated code builds request and response objects for the client which are type-safe and human-readable. gRPC also provides built-in connection management and error handling, and gRPC uses an on-wire format that outperforms JSON in both serialization time and payload size.

With gRPC in the Xpring technology stack, the Xpring team writes code once in order to generate a networking API layer that behaves consistently in every language supported across the Xpring stack. You can check out the pull request to merge gRPC support into rippled here.

Common core functionality

The XRP ecosystem has some common use cases which use a common core of logic. Some examples include:

  • Address derivation and validation
  • Serializing transactions to a binary format
  • Base58 Check Encoding

These sorts of functions are not easy to write or maintain, and now you can outsource this work to the Xpring SDK.

Xpring SDK consumes a common JavaScript core by binding it to the host language and calling into it for core functionality. This common core is not exposed to users of the public API, which minimizes the chances of incorrect use of JavaScript’s type system. Similarly, having just a small number of call sites minimizes the performance impact of the JavaScript virtual machine. Keeping a common core in JavaScript provides the optimal trade off among the benefits of code reuse, performance and a high level of type safety.

Take a look at the common core library in Xpring SDK.

"Glue" code

Xpring SDK binds a common set of core functions and a generated network layer together.

Because the public API is written natively, it provides an idiomatic design in whatever language the SDK is being written in. For example, a JavaScript developer typically expects asynchronous code to use promises, while a Swift developer likely expects a closure completion handler. The Xpring code-sharing patterns allow both of these programmers to write code in the way they’d expect, while still sharing the majority of functionality with each other.

On the importance of modularity

Xpring SDK is built with modularity in mind. Thus, unsupported platforms have a baseline level of support, and third-party developers can make make meaningful contributions to the XRP ecosystem by wrapping up Xpring's open source components.

For example, a developer might be interested in using Python to integrate the XRP Ledger with their exchange. When provided with a gRPC representation of the network interface, this developer can immediately gain access to any network calls they'd like to use. This developer can then wrap up the core library and leverage Xpring SDK's existing code.

With modularity, it’s easy to swap out components and future-proof the Xpring platform. If the Xpring team changes the language that the core code is written in, that will not affect the public API. If the Xpring team decided to use a different networking technology than gRPC, again this change would not affect the public API.

Towards the future

With the architecture described, the cost for Xpring or any external developer to add an additional platform to our SDK is relatively low. You can invoke a program to generate the necessary gRPC networking code, create a lightweight set of bindings between JavaScript and your language of choice, and write the idiomatic public API which glues the two together and is presented to clients. Similarly, adding an additional feature across platforms is easier and cheaper because of the level of code reuse.

The Xpring team is planning to support more features of the XRP Ledger, to increase the number of languages covered by Xpring SDK, and to cover additional services like cross-currency payments and the digital identity system that the Interledger Protocol provides.

How XRP Ledger and Interledger relate to Xpring

Each of Xpring, XRP Ledger, and Interledger are part of an ecosystem that supports a decentralized and open system of sending and receiving value across networks. Which parts you use will depend on what you want to achieve. By developing your apps within this ecosystem, you can implement open, effective, fast, and nearly costless web monetization.

See:

What is the XRP Ledger?

The XRP Ledger is a decentralized cryptographic ledger, powered by a network of peer-to-peer servers. It is the home of XRP, a digital asset designed to bridge the many different currencies in use worldwide. With Xpring SDK, you have out-of-the-box support for the XRP Ledger.

See XRP Ledger for more information.

What is Interledger?

The Interledger Protocol V4 (ILPv4) describes a protocol for sending packets of money across different payment networks or ledgers. Interledger is an open protocol suite for sending payments across different ledgers, and is based on ILPv4. Connectors route packets of money across independent networks in a similar manner to how packets of data are transmitted over the Internet. The open architecture and minimal protocol enable interoperability for any value transfer system.

Interledger is designed to be independent of any company, blockchain, or currency.

Although Xpring straightforwardly supports XRP Ledger, you can also use Xpring with other ledger implementations, such as this Rust implementation of the Interledger Protocol (ILPv4). See Interledger Rust Alpha Release for more details about setting up your own Interledger node.

See Interledger for more information.

Xpring ecosystem brings improved web monetization

Numerous proprietary systems currently exist for sending and receiving value across networks, but these have different drawbacks such as lack of openness, slow speeds, and high costs.

When you use Xpring with the XRP Ledger, or an Interledger implementation, to send or receive value, the low cost and high speed of the transactions enable many additional possibilities for web monetization.

See Web Monetization for more information.

Xpring SDK is currently available for JavaScript, Java, and Swift.

Install the Xpring SDK library

Follow the corresponding instructions for your preferred language.

JavaScript

Install the Xpring-JS package using npm:

$ npm i xpring-js
Java

If you are using Maven, then in your Java project, add the following lines to your pom.xml file in the dependencies object:

<dependency>
  <groupId>io.xpring</groupId>
  <artifactId>xpring4j</artifactId>
  <version>1.0.0</version>
</dependency>


If you are using Gradle, then in your Java project, add the following line to your dependencies section in your build.gradle file:

io.xpring:xpring4j:1.20
Swift

You can use either Carthage or CocoaPods to install Xpring SDK for Swift.

To install via Carthage, add the following line to your Cartfile.

github "xpring-eng/XpringKit"


To install via CocoaPods, add the following line to your Podfile.

pod 'XpringKit'

Obtain credentials for the XRP Ledger Testnet

The XRP Ledger is available on both Mainnet and Testnet. Testnet disburses tokens that have no value, but otherwise functions in an nearly equivalent manner to Mainnet. These tokens are referred to as "test XRP." See XRP Ledger Parallel Networks.

Generate your credentials for Testnet at Xpring Portal. Save these credentials for use when generating a wallet programmatically. This wallet will be loaded with the test equivalent of 1000 XRP, so you can experiment with sending and receiving value on Testnet.

You can also generate Testnet credentials with XRP Faucets. You can generate multiple sets of credentials, and use these to test sending and receiving value between different addresses.

You are now ready to build a simple app.

Build a Simple App

You can build a simple JavaScript app that:

  1. Generates a wallet
  2. Connects to Xpring server
  3. Checks balances
  4. Sends test XRP

The following sections provide JavaScript code snippets that demonstrate these Xpring SDK capabilities.

Generate wallet

Build a wallet using the seed (Secret) from the Testnet credentials that you previously obtained.

const { Wallet } = require("xpring-js");
const seedWallet = Wallet.generateWalletFromSeed("ssZYH1B6yhcAHwRRNRTS1sqCMs7Pb");

Tip: Xpring SDK also supports Hierarchical Deterministic (HD) Wallets.

Connect to server

To check balances and send test XRP, your app must connect to the Xpring-hosted server that is connected to the XRP Ledger. You can reach this endpoint at grpc.xpring.tech:80.

const { Wallet, XpringClient } = require("xpring-js");
const seedWallet = Wallet.generateWalletFromSeed("ssZYH1B6yhcAHwRRNRTS1sqCMs7Pb");
const remoteURL = "grpc.xpring.tech:80";
const xpringClient = new XpringClient(remoteURL);
Check balances

Before sending test XRP, you should check your balance.

const testNetAddress = seedWallet.getAddress();
const balance = await xpringClient.getBalance(testNetAddress);
Send test XRP

To send test XRP, you use the wallet you have created, the amount you have specified, and the recipient address you have specified.

const amount = BigInt("10");
const recipientAddress = "X7u4MQVhU2YxS4P9fWzQjnNuDRUkP3GM6kiVjTjcQgUU3Jr";
const result = await xpringClient.send(amount, recipientAddress, seedWallet)

More examples

For more examples, see the Xpring-JS repository on GitHub.


What is Xpring and Xpring SDK?

Xpring is a solution for developers who want straightforward access to the capabilities of the XRP Ledger, regardless of their knowledge of, or comfort with, cryptography and distributed systems. You can build apps using your preferred language. With Xpring, your app can be used to transact value around the world, regardless of payment size, borders, or the platform you use to build your app.

Xpring SDK delivers the most common features of the XRP ecosystem in an easy to use package. Xpring SDK is the foundation for the Xpring developer site and will also power future Xpring services.

With the Xpring SDK, the following capabilities are supported:

  • Check an account balance
  • Make XRP payments
  • Determine transaction status

Transaction history support is coming soon.

Xpring SDK supports these capabilities across the following languages:

  • Java
  • Swift
  • NodeJS (with browser-based support arriving soon)

All of these features use a common code base, which ensures that Xpring delivers features across all supported languages simultaneously. In practice, this means that an iOS engineer who is integrating the Xpring SDK into their app can explain how to use the APIs to their peer Android engineer.

Architecture

Xpring SDK achieves cross-platform consistency with pragmatic code reuse. At a high level, you can break most multi-platform SDKs, including the Xpring SDK, into three components:

  • Networking and Remote Procedure Calls (RPCs)
  • Common core functionality
  • A public API that connects these features together in an idiomatic API
Networking

Any client-side library needs a reliable way to communicate with a remote service. In the case of Xpring SDK, a client-side library connects to a remote XRP Ledger node which serves data about the state of the XRP Ledger across the distributed system.

Without Xpring SDK, each XRP Ledger server uses a JSON API to communicate and interact with the node. This API has no preconfigured bindings in any language, requiring developers of client libraries to interact with the node by hand-rolling their own untyped JSON objects in their language of choice.

Xpring uses gRPC, which is a cross-platform technology used to define an API using a lightweight markup language. The markup language is then “compiled” to generate code in a number of native languages. The generated code builds request and response objects for the client which are type-safe and human-readable. gRPC also provides built-in connection management and error handling, and gRPC uses an on-wire format that outperforms JSON in both serialization time and payload size.

With gRPC in the Xpring technology stack, the Xpring team writes code once in order to generate a networking API layer that behaves consistently in every language supported across the Xpring stack. You can check out the pull request to merge gRPC support into rippled here.

Common core functionality

The XRP ecosystem has some common use cases which use a common core of logic. Some examples include:

  • Address derivation and validation
  • Serializing transactions to a binary format
  • Base58 Check Encoding

These sorts of functions are not easy to write or maintain, and now you can outsource this work to the Xpring SDK.

Xpring SDK consumes a common JavaScript core by binding it to the host language and calling into it for core functionality. This common core is not exposed to users of the public API, which minimizes the chances of incorrect use of JavaScript’s type system. Similarly, having just a small number of call sites minimizes the performance impact of the JavaScript virtual machine. Keeping a common core in JavaScript provides the optimal trade off among the benefits of code reuse, performance and a high level of type safety.

Take a look at the common core library in Xpring SDK.

"Glue" code

Xpring SDK binds a common set of core functions and a generated network layer together.

Because the public API is written natively, it provides an idiomatic design in whatever language the SDK is being written in. For example, a JavaScript developer typically expects asynchronous code to use promises, while a Swift developer likely expects a closure completion handler. The Xpring code-sharing patterns allow both of these programmers to write code in the way they’d expect, while still sharing the majority of functionality with each other.

On the importance of modularity

Xpring SDK is built with modularity in mind. Thus, unsupported platforms have a baseline level of support, and third-party developers can make make meaningful contributions to the XRP ecosystem by wrapping up Xpring's open source components.

For example, a developer might be interested in using Python to integrate the XRP Ledger with their exchange. When provided with a gRPC representation of the network interface, this developer can immediately gain access to any network calls they'd like to use. This developer can then wrap up the core library and leverage Xpring SDK's existing code.

With modularity, it’s easy to swap out components and future-proof the Xpring platform. If the Xpring team changes the language that the core code is written in, that will not affect the public API. If the Xpring team decided to use a different networking technology than gRPC, again this change would not affect the public API.

Towards the future

With the architecture described, the cost for Xpring or any external developer to add an additional platform to our SDK is relatively low. You can invoke a program to generate the necessary gRPC networking code, create a lightweight set of bindings between JavaScript and your language of choice, and write the idiomatic public API which glues the two together and is presented to clients. Similarly, adding an additional feature across platforms is easier and cheaper because of the level of code reuse.

The Xpring team is planning to support more features of the XRP Ledger, to increase the number of languages covered by Xpring SDK, and to cover additional services like cross-currency payments and the digital identity system that the Interledger Protocol provides.


-->

XRP Ledger

The XRP Ledger is open, ownerless, and ready for you to build on it.

How do I get started?

Start building:
Learn more:

Interledger

Build money into your sites and apps with open standards.

How do I get started?

Start building:
  • ILP Wallet
    Test apps on the latest version of ILP.
  • XpringSDK
    The easiest way to build Interledger into your application
  • SDK Demos
    See the SDK in action in Java, Javascript, and Swift
Learn more:

Web Monetization

A new Internet-native revenue model for content creators.

How do I get started?

Start building:
Learn more:

Use Cases

Xpring is building the tools for developers to build the Internet of Value.

Wallets and Exchanges

XRP is the ultimate bridge currency. Add it to your wallet or exchange.

Start building:
Learn more:

Content

The Web Monetization standard is a new revenue model built into the native architecture of the Internet. No ads. No middlemen. Get paid for what you make. Pay for what you take. That's it.

Learn more:
  • Grant for the Web Announcement
    Coil, Mozilla, and Creative Commons are launching a $100m Grant for the Web to benefit creators and promote the open Web Monetization standard.
  • Grant for the Web
    Initiative to boost open, fair, and inclusive standards and innovation in web monetization.
  • Coil
    Make something, put it online, and get paid. Pay others for their content.
  • Gaming

Enable a new gaming economy where players can own their in-game assets and trade them for other assets or currencies.

Learn more:
Top