diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000000..5b904900620 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,16 @@ +# Bitcore Monorepo Documentation + +This folder aggregates public APIs, SDKs, and UI components across packages. + +- API + - [Bitcore Node REST API](./api/bitcore-node.md) + - [Bitcore Wallet Service API](./api/bitcore-wallet-service.md) +- SDK + - [bitcore-wallet-client](./sdk/bitcore-wallet-client.md) + - [crypto-wallet-core](./sdk/crypto-wallet-core.md) +- UI + - [Insight components](./ui/insight-components.md) + +Notes: +- Base repository scripts are in `package.json`. +- Existing package-specific docs remain under their packages (e.g., `packages/bitcore-node/docs/`). This folder consolidates and links cross-package usage. diff --git a/docs/api/README.md b/docs/api/README.md new file mode 100644 index 00000000000..eacc1b582a4 --- /dev/null +++ b/docs/api/README.md @@ -0,0 +1,4 @@ +# API Documentation Index + +- [Bitcore Node REST API](./bitcore-node.md) +- [Bitcore Wallet Service API](./bitcore-wallet-service.md) diff --git a/docs/api/bitcore-node.md b/docs/api/bitcore-node.md new file mode 100644 index 00000000000..b4b04a7acba --- /dev/null +++ b/docs/api/bitcore-node.md @@ -0,0 +1,92 @@ +# Bitcore Node REST API + +Base URL pattern: `/api/:chain/:network/...` +- `:chain`: BTC | BCH | ETH | MATIC | XRP | DOGE | LTC +- `:network`: mainnet | testnet (lowercase) + +Authentication: Most endpoints are public; wallet endpoints require JWT via `Auth.authenticateMiddleware`. + +## Address +- GET `/:chain/:network/address/:address` — UTXOs + - Query: `unspent=true`, `limit`, `since` +- GET `/:chain/:network/address/:address/txs` — transactions (stream) +- GET `/:chain/:network/address/:address/coins` — coins (stream) +- GET `/:chain/:network/address/:address/balance` — { confirmed, unconfirmed, balance } + +Example: +```bash +curl "http://localhost:3000/api/BTC/mainnet/address/12c6DSiU4Rq3P4ZxziKxzrL5LmMBrzjrJX/balance" +``` + +## Transactions +- GET `/:chain/:network/tx` — list by `blockHeight` or `blockHash` + - Query: `blockHeight` or `blockHash`, `limit`, `since`, `direction`, `paging` +- GET `/:chain/:network/tx/:txId` +- GET `/:chain/:network/tx/:txId/populated` — includes input/output coins +- GET `/:chain/:network/tx/:txId/authhead` +- GET `/:chain/:network/tx/:txid/coins` +- POST `/:chain/:network/tx/send` — broadcast raw tx + - Body: `{ "rawTx": "" }` + +Example broadcast: +```bash +curl -X POST "http://localhost:3000/api/BTC/mainnet/tx/send" \ + -H 'Content-Type: application/json' \ + -d '{"rawTx":""}' +``` + +## Blocks +- GET `/:chain/:network/block` — stream blocks (query: `sinceBlock`, `date`, `limit`, `since`, `direction`, `paging`) +- GET `/:chain/:network/block/tip` — current height +- GET `/:chain/:network/block/:blockId` +- GET `/:chain/:network/block/:blockHash/coins/:limit/:pgnum` — txids, inputs, outputs for block +- GET `/:chain/:network/block/before-time/:time` — block prior to timestamp + +Example: +```bash +curl "http://localhost:3000/api/BTC/mainnet/block/tip" +``` + +## Fees +- GET `/:chain/:network/fee/:target` — dynamic fee for target blocks (0–100) + +## Stats +- GET `/:chain/:network/stats/daily-transactions` — daily tx counts + +## Status +Base: `/api/status` +- GET `/enabled-chains` — enabled {chain,network} +- GET `/performance` — performance tracker info +- GET `/:chain/:network/sync` — { initialSyncComplete } + +## EVM chain helpers (ETH) +Base: defined in `modules/ethereum/api/eth-routes.ts` +- GET `/api/ETH/:network/address/:address/txs/count` — current nonce +- POST `/api/ETH/:network/gas` — estimate gas + - Body: `{ from, to, value, data, gasPrice }` +- GET `/api/ETH/:network/token/:tokenAddress` — ERC20 token info +- GET `/api/ETH/:network/token/:tokenAddress/allowance/:ownerAddress/for/:spenderAddress` +- Multisig (Gnosis Safe): + - GET `/api/ETH/:network/ethmultisig/info/:multisigContractAddress` + - GET `/api/ETH/:network/ethmultisig/:sender/instantiation/:txId` + - GET `/api/ETH/:network/ethmultisig/txps/:multisigContractAddress` + - GET `/api/ETH/:network/ethmultisig/transactions/:multisigContractAddress` (stream) + +Example estimateGas: +```bash +curl -X POST "http://localhost:3000/api/ETH/mainnet/gas" \ + -H 'Content-Type: application/json' \ + -d '{"from":"0x...","to":"0x...","value":"0x0","data":"0x","gasPrice":"0x3b9aca00"}' +``` + +## EVM chain helpers (MATIC) +Base: `modules/matic/api/matic-routes.ts` — same shapes as ETH with chain `MATIC`. +- Nonce, gas, token info +- Multisig info, instantiation, txps, transactions (stream) + +## XRP helpers +- GET `/api/XRP/:network/address/:address/txs/count` — account nonce + +## Notes +- Full examples for many endpoints exist in `packages/bitcore-node/docs/api-documentation.md`. +- Streaming routes keep connections open to push data; prefer a client that can handle chunked responses. diff --git a/docs/api/bitcore-wallet-service.md b/docs/api/bitcore-wallet-service.md new file mode 100644 index 00000000000..ca3fedab7cc --- /dev/null +++ b/docs/api/bitcore-wallet-service.md @@ -0,0 +1,118 @@ +# Bitcore Wallet Service (BWS) API + +Base URL: `/bws/api` +Auth: Most endpoints require headers `x-identity`, `x-signature`, optional `x-session`. See client SDK for signing. + +## Common headers +- `x-client-version`: client version string +- `User-Agent`: propagated to service + +## Version and Status +- GET `/v1/version/` — service version +- GET `/latest-version` — latest Copay/Wallet app version (cached) + +## Wallet lifecycle +- POST `/v2/wallets/` — create wallet +- POST `/v2/wallets/:id/copayers/` — join wallet +- GET `/v3/wallets/` — get status for current wallet +- GET `/v1/wallets/all/` — batch status for multiple identities (header `x-identities`) +- GET `/v1/wallets/:identifier/` — support-staff lookup + +Example create wallet: +```bash +curl -X POST "$BWS/v2/wallets/" \ + -H 'Content-Type: application/json' \ + -H "x-identity: " -H "x-signature: " \ + -d '{"name":"My Wallet","m":1,"n":1,"network":"livenet","coin":"btc"}' +``` + +## Preferences +- GET `/v1/preferences/` +- PUT `/v1/preferences` + +## Addresses +- POST `/v4/addresses/` — create address +- GET `/v1/addresses/` — list addresses (`limit`, `reverse`) +- POST `/v1/addresses/scan/` — start gap-limit scan + +## Balance and UTXOs +- GET `/v1/balance/` — optional `coin`, `tokenAddress`, `multisigContractAddress`, `twoStep` +- GET `/v1/utxos/` — optional `addresses=comma,separated` +- GET `/v1/txcoins/` — `txId` +- GET `/v1/sendmaxinfo/` — compute send-max with fee options + +## Fee levels and gas +- GET `/v2/feelevels/` — `coin|chain`, `network` +- POST `/v3/estimateGas/` — EVM gas estimation via wallet context + +## Tx proposals (TXPs) +- POST `/v3/txproposals/` — create txp +- POST `/v2/txproposals/:id/publish/` +- POST `/v1/txproposals/:id/signatures/` — deprecated +- POST `/v2/txproposals/:id/signatures/` — sign (supports BCH Schnorr) +- POST `/v1/txproposals/:id/broadcast/` +- DELETE `/v1/txproposals/:id/` +- GET `/v1/txproposals/:id/` +- GET `/v2/txproposals/` — pending txps +- GET `/v1/txhistory/` — history (`skip`, `limit`, `tokenAddress`, `multisigContractAddress`, `includeExtendedInfo`) +- POST `/v1/broadcast_raw/` — broadcast raw tx + +Example create+sign+publish (flow outline): +```bash +# 1) create +curl -X POST "$BWS/v3/txproposals/" -H "x-identity: ..." -H "x-signature: ..." \ + -H 'Content-Type: application/json' -d '{"toAddress":"...","amount":10000,"coin":"btc","message":"test"}' +# 2) sign (client generates signatures and posts) +curl -X POST "$BWS/v2/txproposals//signatures/" -H "x-identity: ..." -H "x-signature: ..." \ + -H 'Content-Type: application/json' -d '{"signatures":[""],"maxTxpVersion":3,"supportBchSchnorr":true}' +# 3) publish/broadcast +curl -X POST "$BWS/v1/txproposals//publish/" -H "x-identity: ..." -H "x-signature: ..." +``` + +## Notifications and notes +- GET `/v1/notifications/` — poll with `timeSpan`, `notificationId` +- GET `/v1/txnotes/:txid` +- PUT `/v1/txnotes/:txid/` +- GET `/v1/txnotes/` — optional `minTs` + +## Auth and sessions +- POST `/v1/login/` +- POST `/v1/logout/` + +## Rates +- GET `/v1/fiatrates/:code/` +- GET `/v2/fiatrates/:code/` +- GET `/v3/fiatrates/` +- GET `/v3/fiatrates/:coin/` + +## Utilities +- GET `/v1/nonce/:address` — EVM nonce +- POST `/v1/clearcache/` + +## Third-party services +- OneInch DEX: GET `/v1/service/oneInch/getReferrerFee`, POST `/v1/service/oneInch/getSwap/:chain?`, GET `/v1/service/oneInch/getTokens/:chain?` +- Moonpay: POST `/v1/service/moonpay/*` +- Ramp: POST `/v1/service/ramp/*` +- Simplex: POST `/v1/service/simplex/*`, GET `/v1/service/simplex/events` +- Wyre: POST `/v1/service/wyre/*` +- Changelly: POST `/v1/service/changelly/*` +- PayId: GET `/v1/service/payId/:payId` +- DEX spender whitelist: GET `/v1/services/dex/getSpenderApprovalWhitelist` +- Services data: GET `/v1/services` +- Availability: POST `/v1/service/checkAvailability` + +## Advertisements (staff) +- POST `/v1/advertisements/` +- GET `/v1/advertisements/` +- GET `/v1/advertisements/:adId/` +- GET `/v1/advertisements/country/:country` +- POST `/v1/advertisements/:adId/activate` +- POST `/v1/advertisements/:adId/deactivate` +- DELETE `/v1/advertisements/:adId/` + +## Deprecated endpoints +Numerous v1/v2 routes are retained for legacy clients (e.g., `/v1/feelevels/`, `/v1/addresses/`, `/v1/txproposals/`). Prefer the v2/v3 variants above. + +Notes: +- All authenticated requests must be signed (see client SDK for `x-signature` message format). +- Rate limiting applies to some endpoints (wallet creation, fee levels). diff --git a/docs/sdk/bitcore-wallet-client.md b/docs/sdk/bitcore-wallet-client.md new file mode 100644 index 00000000000..06e36c8edff --- /dev/null +++ b/docs/sdk/bitcore-wallet-client.md @@ -0,0 +1,52 @@ +# bitcore-wallet-client (BWC) + +JavaScript/TypeScript client for Bitcore Wallet Service. + +## Key classes +- `API` — main client, extends EventEmitter (polls notifications) +- `Key` — HD seed manager (mnemonic/xprv), derives `Credentials` +- `Credentials` — serializable wallet identity (chain, network, xpub, request keys) +- `Request` — HTTP wrapper used by API +- `Verifier`, `Utils`, `PayPro`, `PayProV2`, `BulkClient` — helpers + +## Quickstart +```ts +import { API, Key } from 'bitcore-wallet-client'; + +// 1) Point to your BWS instance +const client = new API({ baseUrl: 'http://localhost:3232/bws/api', logLevel: 'info' }); + +// 2) Create a new seed and derive credentials (single-sig BTC, livenet, account 0) +const key = new Key({ seedType: 'new' }); +const credentials = key.createCredentials(undefined, { + coin: 'btc', chain: 'btc', network: 'livenet', account: 0, n: 1 +}); + +// 3) Attach credentials to client +client.fromObj(credentials.toObj()); + +// 4) Create a wallet (server enforces auth via headers built by client) +client['request'].post('/v2/wallets/', { // or use high-level API methods if available + name: 'My Wallet', m: 1, n: 1, network: 'livenet', coin: 'btc' +}, (err, res) => { /* ... */ }); +``` + +## Notifications +```ts +client.initialize({ notificationIncludeOwn: true }, () => { + client.on('notification', n => console.log('notification', n)); +}); +``` + +## Common flows (outline) +- Create/join wallet: POST `/v2/wallets/`, then `/v2/wallets/:id/copayers/` +- Create address: POST `/v4/addresses/` +- Balance: GET `/v1/balance/` +- UTXOs: GET `/v1/utxos/` +- Create TXP: POST `/v3/txproposals/` +- Sign TXP: POST `/v2/txproposals/:id/signatures/` (signatures generated using `Key` + `Utils`) +- Publish/broadcast: POST `/v1/txproposals/:id/publish/` then `/v1/txproposals/:id/broadcast/` + +Notes: +- See `Credentials.FIELDS` for serializable fields and `Key` for encryption helpers. +- The client sets required headers/signatures automatically using the attached credentials. diff --git a/docs/sdk/crypto-wallet-core.md b/docs/sdk/crypto-wallet-core.md new file mode 100644 index 00000000000..881665128d2 --- /dev/null +++ b/docs/sdk/crypto-wallet-core.md @@ -0,0 +1,56 @@ +# crypto-wallet-core (CWC) + +Utility SDK for derivation, validation, and transaction building. + +## Modules and key exports +- `DeriverProxy` — derive addresses/keys across chains +- `ValidationProxy` — address and URI validators per chain +- `TransactionsProxy` — create/sign/get hash/apply signature for chain-specific transactions +- `Paths` — derivation base paths per chain/network + +Chains supported: BTC, BCH, ETH, XRP, DOGE, LTC, MATIC (and ERC20/MULTISIG variants via providers) + +## Derivation +```ts +import Deriver from 'crypto-wallet-core/dist/derivation'; + +const xpub = 'xpub...'; +const address = Deriver.deriveAddress('BTC', 'livenet', xpub, 0, false); + +const xpriv = 'xprv...'; +const { privKey, pubKey, address: ethAddr } = Deriver.derivePrivateKey( + 'ETH', 'livenet', xpriv, 0, false +); +``` + +## Validation +```ts +import Validation from 'crypto-wallet-core/dist/validation'; + +const ok = Validation.validateAddress('BTC', 'mainnet', '12c6DSiU4Rq3P4Zx...'); +const validUri = Validation.validateUri('ETH', 'ethereum:0xabc...?value=1e18'); +``` + +## Transactions +```ts +import Tx from 'crypto-wallet-core/dist/transactions'; + +// Create a BTC tx +const btcHex = Tx.create({ + chain: 'BTC', + inputs: [{ txid: '...', vout: 0, script: '...', satoshis: 10000 }], + outputs: [{ toAddress: '1abc...', satoshis: 9000 }], + change: { address: '1chg...' } +}); + +// Sign EVM tx +const sig = Tx.getSignature({ + chain: 'ETH', + tx: '0x02f8...', + key: { privKey: '', pubKey: '' } +}); +``` + +Notes: +- For ERC20/MULTISIG/MATIC variants, set `chain` to the appropriate key listed in `transactions/index.ts`. +- Address derivation base paths are exposed via `Deriver.pathFor(chain, network, account)`. diff --git a/docs/ui/insight-components.md b/docs/ui/insight-components.md new file mode 100644 index 00000000000..88b03b58384 --- /dev/null +++ b/docs/ui/insight-components.md @@ -0,0 +1,35 @@ +# Insight UI Components + +Public React components/pages exported by `packages/insight`. + +## Pages +- `pages/index.tsx` — Home +- `pages/search.tsx` — Search results +- `pages/address.tsx` — Address view +- `pages/block.tsx` — Block view +- `pages/blocks.tsx` — Recent blocks +- `pages/transaction.tsx` — Transaction view + +Usage (React Router example): +```tsx +}> {/* layout wrapper */} + } /> + } /> + } /> + } /> + +``` + +## Components +- Layout: default export `components/layout.tsx` (wraps header/footer, parallax background) +- BlockDetails: default export `components/block-details.tsx` + - Props: `{ currency: string; network: string; block: string }` +- TransactionDetails: default export `components/transaction-details.tsx` + - Props: `{ transaction: Transaction; currency: string; network: string; refTxid?: string; refVout?: number }` +- EthBlockDetails, TransactionDetailsEth — ETH-specific views +- Header, Footer, Body, Search, Info, ThemeChanger +- Utility components: CopyText, InfiniteScrollLoadSpinner, Coin, CoinList, TransactionSummary + +Notes: +- Data is fetched from Bitcore Node API via `packages/insight/src/api/api.ts` fetcher (axios + SWR patterns). +- Styled components in `assets/styles/*` provide theming (light/dark) and layout primitives.