Skip to content

Commit 454e849

Browse files
GalaxySciTechGalaxySciTech
authored
Merge pull request #34 from GalaxySciTech/cursor/readme-a1f9
Optimize README: improve structure, add chain table, and contact info
2 parents 564ec58 + 86cd76d commit 454e849

1 file changed

Lines changed: 114 additions & 85 deletions

File tree

‎README.md‎

Lines changed: 114 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
11
<h1 align="center">Tokencore</h1>
22

3+
<p align="center">
4+
<strong>Multi-chain cryptocurrency wallet core library for Java</strong>
5+
</p>
6+
37
<p align="center">
48
<a href="https://github.com/galaxyscitech/tokencore/actions">
59
<img src="https://github.com/galaxyscitech/tokencore/actions/workflows/ci.yml/badge.svg" alt="Build Status">
610
</a>
11+
<a href="https://jitpack.io/#galaxyscitech/tokencore">
12+
<img src="https://jitpack.io/v/galaxyscitech/tokencore.svg" alt="JitPack">
13+
</a>
714
<a href="https://github.com/galaxyscitech/tokencore/issues">
815
<img src="https://img.shields.io/github/issues/galaxyscitech/tokencore.svg" alt="Issues">
916
</a>
@@ -18,26 +25,40 @@
1825
</a>
1926
</p>
2027

21-
## Contact
28+
<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;
31+
<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>
34+
</p>
2235

23-
- [GalaxySciTech](https://galaxy.doctor) - Official Website
36+
---
2437

25-
## Use Cases
38+
## Introduction
2639

27-
This serves as the exchange wallet backend. For more details, check out [java-wallet](https://github.com/galaxyscitech/java-wallet).
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.
2841

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

31-
Tokencore is a central component for blockchain wallet backends. It currently supports the following:
44+
## Supported Chains
3245

33-
- BTC, OMNI, ETH, ERC20
34-
- TRX, TRC20, BCH, BSV
35-
- DOGE, DASH, LTC, FILECOIN
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 |
3657

3758
## Requirements
3859

39-
- Java 8+
40-
- Gradle 8.5+ (included via wrapper)
60+
- **Java** 8 or higher
61+
- **Gradle** 8.5+ (included via wrapper, no manual install needed)
4162

4263
## Integration
4364

@@ -71,125 +92,133 @@ dependencies {
7192

7293
## Quick Start
7394

74-
### Initialize Identity
95+
### 1. Initialize Keystore & Identity
7596

7697
```java
77-
try {
78-
Files.createDirectories(Paths.get("${keyStoreProperties.dir}/wallets"));
79-
} catch(Throwable ignored) {}
80-
8198
WalletManager.storage = new KeystoreStorage() {
8299
@Override
83100
public File getKeystoreDir() {
84101
return new File("/path/to/keystore");
85102
}
86103
};
87104
WalletManager.scanWallets();
105+
88106
String password = "your_password";
89107
Identity identity = Identity.getCurrentIdentity();
90108

91109
if (identity == null) {
92-
Identity.createIdentity("token", password, "", Network.MAINNET, Metadata.P2WPKH);
110+
identity = Identity.createIdentity(
111+
"token", password, "", Network.MAINNET, Metadata.P2WPKH);
93112
}
94113
```
95114

96-
### Generate Wallet
115+
### 2. Derive a Wallet
97116

98117
```java
99118
Identity identity = Identity.getCurrentIdentity();
100-
String password = "your_password";
101119
Wallet wallet = identity.deriveWalletByMnemonics(
102-
ChainType.BITCOIN, password, MnemonicUtil.randomMnemonicCodes());
120+
ChainType.BITCOIN, "your_password", MnemonicUtil.randomMnemonicCodes());
103121
System.out.println(wallet.getAddress());
104122
```
105123

106-
## Offline Signature
124+
## Offline Signing
107125

108-
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.
126+
Offline signing creates a digital signature without ever exposing private keys to an online environment.
109127

110128
### Bitcoin
111129

112-
1. **Set Up Transaction Details**
113-
114-
```java
115-
String password = "your_password";
116-
String toAddress = "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9";
117-
int changeIdx = 0;
118-
long amount = 1000L;
119-
long fee = 555L;
120-
```
121-
122-
2. **Fetch UTXOs**
123-
124-
You'll need UTXOs (Unspent Transaction Outputs) for the transaction. Usually, these are fetched from a node or an external API.
125-
126-
```java
127-
ArrayList<BitcoinTransaction.UTXO> utxos = new ArrayList<>();
128-
```
129-
130-
3. **Initialize Transaction & Sign**
131-
132-
```java
133-
BitcoinTransaction bitcoinTransaction = new BitcoinTransaction(
134-
toAddress, changeIdx, amount, fee, utxos);
135-
Wallet wallet = WalletManager.findWalletByAddress(
136-
ChainType.BITCOIN, "33sXfhCBPyHqeVsVthmyYonCBshw5XJZn9");
137-
TxSignResult txSignResult = bitcoinTransaction.signTransaction(
138-
String.valueOf(ChainId.BITCOIN_MAINNET), password, wallet);
139-
System.out.println(txSignResult.getSignedTx());
140-
```
141-
142-
### TRON
143-
144-
1. **Set Up Transaction Details**
145-
146-
```java
147-
String from = "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8";
148-
String to = "TF17BgPaZYbz8oxbjhriubPDsA7ArKoLX3";
149-
long amount = 1;
150-
String password = "your_password";
151-
```
152-
153-
2. **Initialize Transaction & Sign**
154-
155-
```java
156-
TronTransaction transaction = new TronTransaction(from, to, amount);
157-
Wallet wallet = WalletManager.findWalletByAddress(
158-
ChainType.TRON, "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8");
159-
TxSignResult txSignResult = transaction.signTransaction(
160-
"mainnet", password, wallet);
161-
System.out.println(txSignResult.getSignedTx());
162-
```
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+
```
163149

164150
### Ethereum
165151

166152
```java
167153
EthereumTransaction tx = new EthereumTransaction(
168-
BigInteger.ZERO, // nonce
169-
BigInteger.valueOf(20_000_000_000L), // gasPrice
170-
BigInteger.valueOf(21000), // gasLimit
171-
"0xRecipientAddress", // to
172-
BigInteger.valueOf(1_000_000_000_000_000_000L), // value (1 ETH)
173-
"" // data
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
174160
);
175161

176162
Wallet wallet = WalletManager.findWalletByAddress(
177163
ChainType.ETHEREUM, "0xYourAddress");
178164
TxSignResult result = tx.signTransaction(
179-
String.valueOf(ChainId.ETHEREUM_MAINNET), password, wallet);
165+
String.valueOf(ChainId.ETHEREUM_MAINNET), "your_password", wallet);
180166
System.out.println(result.getSignedTx());
181167
```
182168

183-
## Running Tests
169+
### TRON
184170

185-
```bash
186-
./gradlew test
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());
187180
```
188181

189-
## Building
182+
## Build & Test
190183

191184
```bash
185+
# Build the library
192186
./gradlew build
187+
188+
# Run the test suite
189+
./gradlew test
190+
```
191+
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)
193210
```
194211

195-
> **Note**: Tokencore is a functional component for digital currency. It's primarily for learning purposes and doesn't offer a complete blockchain business suite.
212+
## License
213+
214+
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)