From e3b79a912c090774ab92ec8d02f3e4714a128e16 Mon Sep 17 00:00:00 2001 From: Galaxy <30950645+GalaxySciTech@users.noreply.github.com> Date: Fri, 1 May 2026 01:01:51 +0600 Subject: [PATCH] docs: simplify onboarding with 30-second quick start --- README.md | 216 ++++++++++++++++-------------------------------------- 1 file changed, 63 insertions(+), 153 deletions(-) diff --git a/README.md b/README.md index 781537d..8051513 100644 --- a/README.md +++ b/README.md @@ -11,54 +11,72 @@ JitPack - - Issues - - - Pull Requests - - - Contributors - - - License -

- Supported Chains  •  - Quick Start  •  + Quick Start (30s)  •  Integration  •  - Offline Signing  •  - Contact + Recommended Minimum  •  + Supported Chains

--- ## 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 @@ -90,135 +108,27 @@ dependencies { ``` -## 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 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.