Skip to content

Optimize README: improve structure, add chain table, and contact info #34

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
GalaxySciTech merged 1 commit into from
Apr 2, 2026
Merged

Optimize README: improve structure, add chain table, and contact info #34

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 114 additions & 85 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,16 @@
<h1 align="center">Tokencore</h1>

<p align="center">
<strong>Multi-chain cryptocurrency wallet core library for Java</strong>
</p>

<p align="center">
<a href="https://github.com/galaxyscitech/tokencore/actions">
<img src="https://github.com/galaxyscitech/tokencore/actions/workflows/ci.yml/badge.svg" alt="Build Status">
</a>
<a href="https://jitpack.io/#galaxyscitech/tokencore">
<img src="https://jitpack.io/v/galaxyscitech/tokencore.svg" alt="JitPack">
</a>
<a href="https://github.com/galaxyscitech/tokencore/issues">
<img src="https://img.shields.io/github/issues/galaxyscitech/tokencore.svg" alt="Issues">
</a>
Expand All @@ -18,26 +25,40 @@
</a>
</p>

## Contact
<p align="center">
<a href="#supported-chains">Supported Chains</a> &nbsp;&bull;&nbsp;
<a href="#quick-start">Quick Start</a> &nbsp;&bull;&nbsp;
<a href="#integration">Integration</a> &nbsp;&bull;&nbsp;
<a href="#offline-signing">Offline Signing</a> &nbsp;&bull;&nbsp;
<a href="#contact">Contact</a>
</p>

- [GalaxySciTech](https://galaxy.doctor) - Official Website
---

## Use Cases
## Introduction

This serves as the exchange wallet backend. For more details, check out [java-wallet](https://github.com/galaxyscitech/java-wallet).
Tokencore is a lightweight Java library that provides core wallet functionality for multiple blockchains. It handles HD wallet derivation, encrypted keystore management, and offline transaction signing — making it the ideal building block for exchange backends and custodial wallet services.

## Introduction
For a complete exchange wallet backend built on top of Tokencore, see [java-wallet](https://github.com/galaxyscitech/java-wallet).

Tokencore is a central component for blockchain wallet backends. It currently supports the following:
## Supported Chains

- BTC, OMNI, ETH, ERC20
- TRX, TRC20, BCH, BSV
- DOGE, DASH, LTC, FILECOIN
| Chain | Token Standards | Features |
|-------|----------------|----------|
| **Bitcoin** | BTC, OMNI | UTXO management, SegWit (P2WPKH) |
| **Ethereum** | ETH, ERC-20 | Offline signing, nonce management |
| **TRON** | TRX, TRC-20 | Transaction signing |
| **Bitcoin Cash** | BCH | CashAddr format |
| **Bitcoin SV** | BSV | Transaction signing |
| **Litecoin** | LTC | Transaction signing |
| **Dogecoin** | DOGE | Transaction signing |
| **Dash** | DASH | Transaction signing |
| **Filecoin** | FIL | Transaction signing |

## Requirements

- Java 8+
- Gradle 8.5+ (included via wrapper)
- **Java** 8 or higher
- **Gradle** 8.5+ (included via wrapper, no manual install needed)

## Integration

Expand Down Expand Up @@ -71,125 +92,133 @@ dependencies {

## Quick Start

### Initialize Identity
### 1. Initialize Keystore & Identity

```java
try {
Files.createDirectories(Paths.get("${keyStoreProperties.dir}/wallets"));
} catch(Throwable ignored) {}

WalletManager.storage = new KeystoreStorage() {
@Override
public File getKeystoreDir() {
return new File("/path/to/keystore");
}
};
WalletManager.scanWallets();

String password = "your_password";
Identity identity = Identity.getCurrentIdentity();

if (identity == null) {
Identity.createIdentity("token", password, "", Network.MAINNET, Metadata.P2WPKH);
identity = Identity.createIdentity(
"token", password, "", Network.MAINNET, Metadata.P2WPKH);
}
```

### Generate Wallet
### 2. Derive a Wallet

```java
Identity identity = Identity.getCurrentIdentity();
String password = "your_password";
Wallet wallet = identity.deriveWalletByMnemonics(
ChainType.BITCOIN, password, MnemonicUtil.randomMnemonicCodes());
ChainType.BITCOIN, "your_password", MnemonicUtil.randomMnemonicCodes());
System.out.println(wallet.getAddress());
```

## Offline Signature
## Offline Signing

Offline signing refers to the process of creating a digital signature for a transaction without connecting to the internet. This method enhances security by ensuring private keys never come in contact with an online environment.
Offline signing creates a digital signature without ever exposing private keys to an online environment.

### Bitcoin

1. **Set Up Transaction Details**

```java
String password = "your_password";
String toAddress = "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9";
int changeIdx = 0;
long amount = 1000L;
long fee = 555L;
```

2. **Fetch UTXOs**

You'll need UTXOs (Unspent Transaction Outputs) for the transaction. Usually, these are fetched from a node or an external API.

```java
ArrayList<BitcoinTransaction.UTXO> utxos = new ArrayList<>();
```

3. **Initialize Transaction & Sign**

```java
BitcoinTransaction bitcoinTransaction = new BitcoinTransaction(
toAddress, changeIdx, amount, fee, utxos);
Wallet wallet = WalletManager.findWalletByAddress(
ChainType.BITCOIN, "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9");
TxSignResult txSignResult = bitcoinTransaction.signTransaction(
String.valueOf(ChainId.BITCOIN_MAINNET), password, wallet);
System.out.println(txSignResult.getSignedTx());
```

### TRON

1. **Set Up Transaction Details**

```java
String from = "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8";
String to = "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3";
long amount = 1;
String password = "your_password";
```

2. **Initialize Transaction & Sign**

```java
TronTransaction transaction = new TronTransaction(from, to, amount);
Wallet wallet = WalletManager.findWalletByAddress(
ChainType.TRON, "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8");
TxSignResult txSignResult = transaction.signTransaction(
"mainnet", password, wallet);
System.out.println(txSignResult.getSignedTx());
```
```java
// 1. Define transaction parameters
String toAddress = "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9";
int changeIdx = 0;
long amount = 1000L;
long fee = 555L;

// 2. Collect UTXOs (from your node or a third-party API)
ArrayList<BitcoinTransaction.UTXO> utxos = new ArrayList<>();

// 3. Build and sign
BitcoinTransaction bitcoinTransaction = new BitcoinTransaction(
toAddress, changeIdx, amount, fee, utxos);
Wallet wallet = WalletManager.findWalletByAddress(
ChainType.BITCOIN, "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9");
TxSignResult txSignResult = bitcoinTransaction.signTransaction(
String.valueOf(ChainId.BITCOIN_MAINNET), "your_password", wallet);
System.out.println(txSignResult.getSignedTx());
```

### Ethereum

```java
EthereumTransaction tx = new EthereumTransaction(
BigInteger.ZERO, // nonce
BigInteger.valueOf(20_000_000_000L), // gasPrice
BigInteger.valueOf(21000), // gasLimit
"0xRecipientAddress", // to
BigInteger.valueOf(1_000_000_000_000_000_000L), // value (1 ETH)
"" // data
BigInteger.ZERO, // nonce
BigInteger.valueOf(20_000_000_000L), // gasPrice
BigInteger.valueOf(21_000), // gasLimit
"0xRecipientAddress", // to
BigInteger.valueOf(1_000_000_000_000_000_000L), // value (1 ETH)
"" // data
);

Wallet wallet = WalletManager.findWalletByAddress(
ChainType.ETHEREUM, "0xYourAddress");
TxSignResult result = tx.signTransaction(
String.valueOf(ChainId.ETHEREUM_MAINNET), password, wallet);
String.valueOf(ChainId.ETHEREUM_MAINNET), "your_password", wallet);
System.out.println(result.getSignedTx());
```

## Running Tests
### TRON

```bash
./gradlew test
```java
String from = "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8";
String to = "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3";

TronTransaction transaction = new TronTransaction(from, to, 1L);
Wallet wallet = WalletManager.findWalletByAddress(ChainType.TRON, from);
TxSignResult result = transaction.signTransaction(
"mainnet", "your_password", wallet);
System.out.println(result.getSignedTx());
```

## Building
## Build & Test

```bash
# Build the library
./gradlew build

# Run the test suite
./gradlew test
```

## Project Structure

```
src/main/java/org/consenlabs/tokencore/
├── wallet/
│ ├── Identity.java # HD identity management
│ ├── Wallet.java # Wallet abstraction
│ ├── WalletManager.java # Wallet lifecycle & discovery
│ ├── address/ # Chain-specific address generation
│ ├── keystore/ # Encrypted keystore implementations
│ ├── model/ # ChainType, ChainId, Metadata, etc.
│ ├── network/ # Bitcoin-fork network parameters
│ ├── transaction/ # Offline signing per chain
│ └── validators/ # Address & key validation
└── foundation/
├── crypto/ # AES, KDF, hashing primitives
├── utils/ # Mnemonic, numeric, byte helpers
└── rlp/ # RLP encoding (Ethereum)
```

> **Note**: Tokencore is a functional component for digital currency. It's primarily for learning purposes and doesn't offer a complete blockchain business suite.
## License

This project is licensed under the [GNU General Public License v3.0](LICENSE).

## Contact

- **Telegram**: [t.me/GalaxySciTech](https://t.me/GalaxySciTech)
- **Website**: [galaxy.doctor](https://galaxy.doctor)
- **GitHub Issues**: [Report a bug](https://github.com/galaxyscitech/tokencore/issues/new)

---

> **Disclaimer**: Tokencore is a functional component for digital currency operations. It is intended primarily for learning and development purposes and does not provide a complete blockchain business solution. Use at your own risk.
Loading