diff --git a/README.md b/README.md index 7dce965..781537d 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,16 @@

Tokencore

+

+ Multi-chain cryptocurrency wallet core library for Java +

+

Build Status + + JitPack + Issues @@ -18,26 +25,40 @@

-## Contact +

+ Supported Chains  •  + Quick Start  •  + Integration  •  + Offline Signing  •  + Contact +

-- [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 @@ -71,13 +92,9 @@ 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() { @@ -85,111 +102,123 @@ WalletManager.storage = new KeystoreStorage() { } }; 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 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 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.