Skip to content

docs: add 30-second quick start and streamline README for easy onboarding #35

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 30, 2026
Merged

docs: add 30-second quick start and streamline README for easy onboarding #35

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
216 changes: 63 additions & 153 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,54 +11,72 @@
<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>
<a href="https://github.com/galaxyscitech/tokencore/pulls">
<img src="https://img.shields.io/github/issues-pr/galaxyscitech/tokencore.svg" alt="Pull Requests">
</a>
<a href="https://github.com/galaxyscitech/tokencore/graphs/contributors">
<img src="https://img.shields.io/github/contributors/galaxyscitech/tokencore.svg" alt="Contributors">
</a>
<a href="LICENSE">
<img src="https://img.shields.io/github/license/galaxyscitech/tokencore.svg" alt="License">
</a>
</p>

<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="#quick-start-30-seconds">Quick Start (30s)</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>
<a href="#core-features-recommended-minimum">Recommended Minimum</a> &nbsp;&bull;&nbsp;
<a href="#supported-chains">Supported Chains</a>
</p>

---

## Introduction

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.
Tokencore is a lightweight Java library for wallet fundamentals: HD derivation, encrypted keystore management, and offline signing.

For a complete exchange wallet backend built on top of Tokencore, see [java-wallet](https://github.com/galaxyscitech/java-wallet).
If your goal is "install and use immediately", start with the 30-second quick start below and only enable additional chains/features later.

## Supported Chains
## Quick Start (30 seconds)

| 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 |
### 1) Add dependency

```gradle
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation 'com.github.galaxyscitech:tokencore:1.3.0'
}
```

### 2) Copy this minimal bootstrap code

```java
WalletManager.storage = () -> new File("./keystore");
WalletManager.scanWallets();

String password = "change_me";
Identity identity = Identity.getCurrentIdentity();
if (identity == null) {
identity = Identity.createIdentity("default", password, "", Network.MAINNET, Metadata.P2WPKH);
}

Wallet wallet = identity.deriveWalletByMnemonics(
ChainType.ETHEREUM,
password,
MnemonicUtil.randomMnemonicCodes());

System.out.println("Address = " + wallet.getAddress());
```

### 3) Verify locally

```bash
./gradlew test
```

## Requirements
## Core Features (Recommended Minimum)

- **Java** 8 or higher
- **Gradle** 8.5+ (included via wrapper, no manual install needed)
For new integrators, keep the initial rollout small:

1. **Identity + keystore only** (account generation + secure storage)
2. **Single chain first** (recommend: ETH or BTC)
3. **Offline signing only** (avoid online key usage)
4. **No multi-chain abstraction in v1 API surface**

This reduces integration complexity and speeds up first successful deployment.

## Integration

Expand Down Expand Up @@ -90,135 +108,27 @@ dependencies {
</dependency>
```

## Quick Start

### 1. Initialize Keystore & Identity

```java
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 = Identity.createIdentity(
"token", password, "", Network.MAINNET, Metadata.P2WPKH);
}
```

### 2. Derive a Wallet

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

## Offline Signing

Offline signing creates a digital signature without ever exposing private keys to an online environment.

### Bitcoin

```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(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), "your_password", wallet);
System.out.println(result.getSignedTx());
```

### TRON
## Supported Chains

```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());
```
| 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 |

## 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)
```

## 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