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-javasubdirectory 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
| Link | Description |
|---|---|
| radixdlt.com | Radix DLT Homepage |
| documentation | Radix Knowledge Base |
| forum | Radix Technical Forum |
| @radixdlt | Follow Radix DLT on Twitter |
License
The radixdlt-java library is released under the MIT License.