Skip to content

Commit 2c11142

Browse files
GalaxySciTechGalaxySciTech
authored
Merge pull request #35 from GalaxySciTech/codex
docs: add 30-second quick start and streamline README for easy onboarding
2 parents 454e849 + e3b79a9 commit 2c11142

1 file changed

Lines changed: 63 additions & 153 deletions

File tree

‎README.md‎

Lines changed: 63 additions & 153 deletions
Original file line numberDiff line numberDiff line change
@@ -11,54 +11,72 @@
1111
<a href="https://jitpack.io/#galaxyscitech/tokencore">
1212
<img src="https://jitpack.io/v/galaxyscitech/tokencore.svg" alt="JitPack">
1313
</a>
14-
<a href="https://github.com/galaxyscitech/tokencore/issues">
15-
<img src="https://img.shields.io/github/issues/galaxyscitech/tokencore.svg" alt="Issues">
16-
</a>
17-
<a href="https://github.com/galaxyscitech/tokencore/pulls">
18-
<img src="https://img.shields.io/github/issues-pr/galaxyscitech/tokencore.svg" alt="Pull Requests">
19-
</a>
20-
<a href="https://github.com/galaxyscitech/tokencore/graphs/contributors">
21-
<img src="https://img.shields.io/github/contributors/galaxyscitech/tokencore.svg" alt="Contributors">
22-
</a>
23-
<a href="LICENSE">
24-
<img src="https://img.shields.io/github/license/galaxyscitech/tokencore.svg" alt="License">
25-
</a>
2614
</p>
2715

2816
<p align="center">
29-
<a href="#supported-chains">Supported Chains</a> &nbsp;&bull;&nbsp;
30-
<a href="#quick-start">Quick Start</a> &nbsp;&bull;&nbsp;
17+
<a href="#quick-start-30-seconds">Quick Start (30s)</a> &nbsp;&bull;&nbsp;
3118
<a href="#integration">Integration</a> &nbsp;&bull;&nbsp;
32-
<a href="#offline-signing">Offline Signing</a> &nbsp;&bull;&nbsp;
33-
<a href="#contact">Contact</a>
19+
<a href="#core-features-recommended-minimum">Recommended Minimum</a> &nbsp;&bull;&nbsp;
20+
<a href="#supported-chains">Supported Chains</a>
3421
</p>
3522

3623
---
3724

3825
## Introduction
3926

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

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

44-
## Supported Chains
31+
## Quick Start (30 seconds)
4532

46-
| Chain | Token Standards | Features |
47-
|-------|----------------|----------|
48-
| **Bitcoin** | BTC, OMNI | UTXO management, SegWit (P2WPKH) |
49-
| **Ethereum** | ETH, ERC-20 | Offline signing, nonce management |
50-
| **TRON** | TRX, TRC-20 | Transaction signing |
51-
| **Bitcoin Cash** | BCH | CashAddr format |
52-
| **Bitcoin SV** | BSV | Transaction signing |
53-
| **Litecoin** | LTC | Transaction signing |
54-
| **Dogecoin** | DOGE | Transaction signing |
55-
| **Dash** | DASH | Transaction signing |
56-
| **Filecoin** | FIL | Transaction signing |
33+
### 1) Add dependency
34+
35+
```gradle
36+
repositories {
37+
maven { url 'https://jitpack.io' }
38+
}
39+
dependencies {
40+
implementation 'com.github.galaxyscitech:tokencore:1.3.0'
41+
}
42+
```
43+
44+
### 2) Copy this minimal bootstrap code
45+
46+
```java
47+
WalletManager.storage = () -> new File("./keystore");
48+
WalletManager.scanWallets();
49+
50+
String password = "change_me";
51+
Identity identity = Identity.getCurrentIdentity();
52+
if (identity == null) {
53+
identity = Identity.createIdentity("default", password, "", Network.MAINNET, Metadata.P2WPKH);
54+
}
55+
56+
Wallet wallet = identity.deriveWalletByMnemonics(
57+
ChainType.ETHEREUM,
58+
password,
59+
MnemonicUtil.randomMnemonicCodes());
60+
61+
System.out.println("Address = " + wallet.getAddress());
62+
```
63+
64+
### 3) Verify locally
65+
66+
```bash
67+
./gradlew test
68+
```
5769

58-
## Requirements
70+
## Core Features (Recommended Minimum)
5971

60-
- **Java** 8 or higher
61-
- **Gradle** 8.5+ (included via wrapper, no manual install needed)
72+
For new integrators, keep the initial rollout small:
73+
74+
1. **Identity + keystore only** (account generation + secure storage)
75+
2. **Single chain first** (recommend: ETH or BTC)
76+
3. **Offline signing only** (avoid online key usage)
77+
4. **No multi-chain abstraction in v1 API surface**
78+
79+
This reduces integration complexity and speeds up first successful deployment.
6280

6381
## Integration
6482

@@ -90,135 +108,27 @@ dependencies {
90108
</dependency>
91109
```
92110

93-
## Quick Start
94-
95-
### 1. Initialize Keystore & Identity
96-
97-
```java
98-
WalletManager.storage = new KeystoreStorage() {
99-
@Override
100-
public File getKeystoreDir() {
101-
return new File("/path/to/keystore");
102-
}
103-
};
104-
WalletManager.scanWallets();
105-
106-
String password = "your_password";
107-
Identity identity = Identity.getCurrentIdentity();
108-
109-
if (identity == null) {
110-
identity = Identity.createIdentity(
111-
"token", password, "", Network.MAINNET, Metadata.P2WPKH);
112-
}
113-
```
114-
115-
### 2. Derive a Wallet
116-
117-
```java
118-
Identity identity = Identity.getCurrentIdentity();
119-
Wallet wallet = identity.deriveWalletByMnemonics(
120-
ChainType.BITCOIN, "your_password", MnemonicUtil.randomMnemonicCodes());
121-
System.out.println(wallet.getAddress());
122-
```
123-
124-
## Offline Signing
125-
126-
Offline signing creates a digital signature without ever exposing private keys to an online environment.
127-
128-
### Bitcoin
129-
130-
```java
131-
// 1. Define transaction parameters
132-
String toAddress = "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9";
133-
int changeIdx = 0;
134-
long amount = 1000L;
135-
long fee = 555L;
136-
137-
// 2. Collect UTXOs (from your node or a third-party API)
138-
ArrayList<BitcoinTransaction.UTXO> utxos = new ArrayList<>();
139-
140-
// 3. Build and sign
141-
BitcoinTransaction bitcoinTransaction = new BitcoinTransaction(
142-
toAddress, changeIdx, amount, fee, utxos);
143-
Wallet wallet = WalletManager.findWalletByAddress(
144-
ChainType.BITCOIN, "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9");
145-
TxSignResult txSignResult = bitcoinTransaction.signTransaction(
146-
String.valueOf(ChainId.BITCOIN_MAINNET), "your_password", wallet);
147-
System.out.println(txSignResult.getSignedTx());
148-
```
149-
150-
### Ethereum
151-
152-
```java
153-
EthereumTransaction tx = new EthereumTransaction(
154-
BigInteger.ZERO, // nonce
155-
BigInteger.valueOf(20_000_000_000L), // gasPrice
156-
BigInteger.valueOf(21_000), // gasLimit
157-
"0xRecipientAddress", // to
158-
BigInteger.valueOf(1_000_000_000_000_000_000L), // value (1 ETH)
159-
"" // data
160-
);
161-
162-
Wallet wallet = WalletManager.findWalletByAddress(
163-
ChainType.ETHEREUM, "0xYourAddress");
164-
TxSignResult result = tx.signTransaction(
165-
String.valueOf(ChainId.ETHEREUM_MAINNET), "your_password", wallet);
166-
System.out.println(result.getSignedTx());
167-
```
168-
169-
### TRON
111+
## Supported Chains
170112

171-
```java
172-
String from = "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8";
173-
String to = "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3";
174-
175-
TronTransaction transaction = new TronTransaction(from, to, 1L);
176-
Wallet wallet = WalletManager.findWalletByAddress(ChainType.TRON, from);
177-
TxSignResult result = transaction.signTransaction(
178-
"mainnet", "your_password", wallet);
179-
System.out.println(result.getSignedTx());
180-
```
113+
| Chain | Token Standards | Features |
114+
|-------|----------------|----------|
115+
| **Bitcoin** | BTC, OMNI | UTXO management, SegWit (P2WPKH) |
116+
| **Ethereum** | ETH, ERC-20 | Offline signing, nonce management |
117+
| **TRON** | TRX, TRC-20 | Transaction signing |
118+
| **Bitcoin Cash** | BCH | CashAddr format |
119+
| **Bitcoin SV** | BSV | Transaction signing |
120+
| **Litecoin** | LTC | Transaction signing |
121+
| **Dogecoin** | DOGE | Transaction signing |
122+
| **Dash** | DASH | Transaction signing |
123+
| **Filecoin** | FIL | Transaction signing |
181124

182125
## Build & Test
183126

184127
```bash
185-
# Build the library
186128
./gradlew build
187-
188-
# Run the test suite
189129
./gradlew test
190130
```
191131

192-
## Project Structure
193-
194-
```
195-
src/main/java/org/consenlabs/tokencore/
196-
├── wallet/
197-
│ ├── Identity.java # HD identity management
198-
│ ├── Wallet.java # Wallet abstraction
199-
│ ├── WalletManager.java # Wallet lifecycle & discovery
200-
│ ├── address/ # Chain-specific address generation
201-
│ ├── keystore/ # Encrypted keystore implementations
202-
│ ├── model/ # ChainType, ChainId, Metadata, etc.
203-
│ ├── network/ # Bitcoin-fork network parameters
204-
│ ├── transaction/ # Offline signing per chain
205-
│ └── validators/ # Address & key validation
206-
└── foundation/
207-
├── crypto/ # AES, KDF, hashing primitives
208-
├── utils/ # Mnemonic, numeric, byte helpers
209-
└── rlp/ # RLP encoding (Ethereum)
210-
```
211-
212132
## License
213133

214134
This project is licensed under the [GNU General Public License v3.0](LICENSE).
215-
216-
## Contact
217-
218-
- **Telegram**: [t.me/GalaxySciTech](https://t.me/GalaxySciTech)
219-
- **Website**: [galaxy.doctor](https://galaxy.doctor)
220-
- **GitHub Issues**: [Report a bug](https://github.com/galaxyscitech/tokencore/issues/new)
221-
222-
---
223-
224-
> **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.

0 commit comments

Comments
 (0)