IMPORTANT

This repository has been archived as part of our move to a monorepo.

• Monorepo is here
• The code for this repo is available in the radixdlt-java subdirectory of the monorepo.

radixdlt-java

radixdlt-java is a Java/Android Client library for interacting with a Radix Distributed Ledger.

Table of contents

• Changelog
• Features
• Installation
• Getting started
• Radix Application API
• Code examples
• Contribute
• Links
• License

Features

• Connection to the Betanet test network
• Fee-less transactions for testnets
• Public Key Identity Creation
• Token Creation (ERC-777 style)
• Message sending
• RXJava 2 based
• Utilizes JSON-RPC over Websockets

Installation

Include the following gradle dependency:

Gradle

repositories {
    maven { url 'https://jitpack.io' }
}

dependencies {
    implementation 'com.radixdlt:radixdlt-java:1.0-beta.19'
}

Getting Started

Identities

An Identity is the user's credentials (or more technically the manager of the public/private key pair) into the ledger, allowing a user to own tokens and send tokens as well as decrypt data.

To create/load an identity from a file:

RadixIdentity identity = RadixIdentities.loadOrCreateEncryptedFile("filename.key", "password123");

This will either create or load a file with a public/private key and encrypted with the given password.

Universes

A Universe is an instance of a Radix Distributed Ledger which is defined by a genesis atom and a dynamic set of unpermissioned nodes forming a network.

A predefined configuration to bootstrap into the betanet network is available:

BootstrapConfig config = Bootstrap.BETANET;

Radix Application API

The Radix Application API is a client side API exposing high level abstractions to make DAPP creation easier.

To initialize the API:

RadixApplicationAPI api = RadixApplicationAPI.create(Bootstrap.BETANET, identity);

To continually sync and pull from the network ledger on your account:

Disposable d = api.pull();

To stop syncing:

d.dispose();

Addresses

An address is a reference to an account and allows a user to receive tokens and/or data from other users.

You can get your own address by:

RadixAddress myAddress = api.getAddress();

Or from a base58 string:

RadixAddress anotherAddress = RadixAddress.fromString("JHB89drvftPj6zVCNjnaijURk8D8AMFw4mVja19aoBGmRXWchnJ");

Code Examples

Sending Messages

Immutable data can be stored on the ledger. The data can be encrypted so that only selected identities can read the data.

To send the encrypted string Hello which only the sender and recipient can read:

Result result = api.sendMessage(<to-address>, "Hello".getBytes(StandardCharsets.UTF_8), true);
result.blockUntilComplete();

To send the unencrypted string Hello:

Result result = api.sendMessage(<to-address>, "Hello".getBytes(StandardCharsets.UTF_8), false);
result.blockUntilComplete();

Or equivalently,

SendMessageAction msgAction = SendMessageAction.create(api.getAddress(), <to-address>, "Hello".getBytes(StandardCharset.UTF_8), false);
Result result = api.execute(msgAction);
result.blockUntilComplete();

Receiving Messages

To then read (and decrypt if necessary) all the readable data sent to you:

Observable<DecryptedMessage> readable = api.observeMessages();
readable.subscribe(data -> { ... });

Creating Tokens

To create a token, an RRI or radix resource identifier must first be constructed:

RRI tokenRRI = RRI.of(api.getAddress(), "NEW");

To create a fixed-supply token:

Result result = api.createFixedSupplyToken(tokenRRI, "New Token", "The Best Token", BigDecimal.valueOf(1000.0));
result.blockUntilComplete();

To create a multi-issuance token:

Result result = api.createMultiIssuance(tokenRRI, "New Token", "The Best Token");
result.blockUntilComplete();

Or equivalently,

CreateTokenAction createAction = CreateTokenAction.create(
  tokenRRI,
  "New Token",
  "The Best Token",
  BigDecimal.ZERO,
  TokenUnitConversions.getMinimumGranularity(),
  TokenSupplyType.MUTABLE
); 
Result result = api.execute(createAction);
result.blockUntilComplete();

Minting Tokens

To mint 1000 tokens (must be multi-issuance) in your account:

Result result = api.mintTokens(tokenRRI, BigDecimal.valueOf(1000.0));
result.blockUntilComplete();

Or equivalently,

MintTokensAction mintAction = MintTokensAction.create(tokenRRI, api.getAddress(), BigDecimal.valueOf(1000.0));
Result result = api.execute(mintAction);
result.blockUntilComplete();

Burning Tokens

To burn 1000 tokens (must be multi-issuance) in your account:

Result result = api.burnTokens(tokenRRI, BigDecimal.valueOf(1000.0));
result.blockUntilComplete();

Or equivalently,

BurnTokensAction burnAction = BurnTokensAction.create(tokenRRI, api.getAddress(), BigDecimal.valueOf(1000.0));
Result result = api.execute(burnAction);
result.blockUntilComplete();

Sending Tokens

To send an amount from my address to another address:

Result result = api.sendTokens(tokenRRI, BigDecimal.valueOf(10.99), <to-address>);
result.blockUntilComplete();

Or equivalently,

TransferTokensAction sendAction = TransferTokensAction.create(
  tokenRRI,
  api.getAddress(),
  <to-address>,
  BigDecimal.valueOf(10.00),
  null
);
Result result = api.execute(sendAction);
result.blockUntilComplete();

Retrieving Tokens

To retrieve all of the token transfers which have occurred in my account:

Observable<TokenTransfer> transfers = api.observeTokenTransfers();
transfers.subscribe(tx -> { ... });

To get a stream of the balance of tokens in my account:

Observable<BigDecimal> balance = api.observeBalance(tokenRRI);
balance.subscribe(bal -> { ... });

Executing Atomic Transactions

To execute an atomic transaction of creating a token, minting, then sending:

CreateTokensAction createAction = CreateTokenAction.create(
  tokenRRI,
  "Joshy Token",
  "The Best Coin Ever",
  BigDecimal.ZERO,
  TokenUnitConversions.getMinimumGranularity(),
  TokenSupplyType.MUTABLE
);
MintTokensAction mintAction = MintTokensAction.create(
  tokenRRI,
  api.getAddress(),
  BigDecimal.valueOf(1000000.0)
);
TransferTokensAction transferAction =  TransferTokensAction.create(
  tokenRRI,
  api.getAddress(),
  <to-address>,
  BigDecimal.valueOf(1000000.0),
  null
);

Transaction tx = api.createTransaction();
tx.stage(createAction);
tx.stage(mintAction);
tx.stage(transferAction);
Result result = tx.commitAndPush();
result.blockUntilComplete();

Contribute

Contributions are welcome, we simply ask to:

• Fork the codebase
• Make changes
• Submit a pull request for review

When contributing to this repository, we recommend discussing with the development team the change you wish to make using a GitHub issue before making changes.

Please follow our Code of Conduct in all your interactions with the project.

Links

License

The radixdlt-java library is released under the MIT License.