{"_id":"@brynjarrr/xchain-client","_rev":"1-6c41e5a4f97279ae85b94fd716e7bdec","name":"@brynjarrr/xchain-client","dist-tags":{"latest":"0.11.1"},"versions":{"0.11.1":{"name":"@brynjarrr/xchain-client","version":"0.11.1","license":"MIT","main":"lib/index","types":"lib/index","scripts":{"build":"yarn run clean && yarn run compile","clean":"rimraf -rf ./lib","compile":"tsc -p tsconfig.build.json","prepublishOnly":"yarn run build","test":"jest --passWithNoTests"},"devDependencies":{"@xchainjs/xchain-crypto":"^0.2.6","@xchainjs/xchain-util":"^0.5.1","axios":"^0.25.0"},"peerDependencies":{"@xchainjs/xchain-crypto":"^0.2.6","@xchainjs/xchain-util":"^0.5.1","axios":"^0.25.0"},"gitHead":"515ef43a4f0e3aa11644c69f7025caf0f0a0c1db","description":"A specification for a generalised interface for crypto wallets clients, to be used by XChainJS implementations. The client should not have any functionality to generate a key, instead, the `asgardex-crypto` library should be used to ensure cross-chain com","_id":"@brynjarrr/xchain-client@0.11.1","_nodeVersion":"16.5.0","_npmVersion":"lerna/3.22.1/node@v16.5.0+arm64 (darwin)","dist":{"integrity":"sha512-AgLB7CvLYEAFfNRtNzl1X3T+kvxaEX2r1tvAABqvznrstq1uR53xMSsLVMSHQPUTAWJU6DCYxczsvhHvC2jLuA==","shasum":"39428466e610fc598f5512ef36ce43ccc9f7cd21","tarball":"https://registry.npmjs.org/@brynjarrr/xchain-client/-/xchain-client-0.11.1.tgz","fileCount":21,"unpackedSize":50457,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v4.10.10\r\nComment: https://openpgpjs.org\r\n\r\nwsFzBAEBCAAGBQJiPbTxACEJED1NWxICdlZqFiEECWMYAoorWMhJKdjhPU1b\r\nEgJ2Vmqmvw/+JaSpo48Q/mBRq4JmBxoHRlTMKQSo3mekqJun4CdaqFXD/Cdd\r\n8OkaNjgo/fqt3sWyCUOgmu5smewoUDl61THhMVAdfhr7LQQ5d79GfMXXrNtj\r\nLC+WrRfCnqymbtefsDOTlrJP0d2ekzK7b1PBy3RBC2B1zCtQOywhatiWo5Ez\r\npOKISZiJ8HhK5B6p6BMC086A5P/vHLjkSx53yIrmsNXLJsEf4aqMMjYGzoeT\r\n7vnutqZd/ZTptzDkROXXJHRSAjVhiSB/Ka9u/Bli+QCAt5PLDykOqVKjeOhi\r\nRHYZKoetQZLUw9epAEO7gOHRuLy8zq5ScEWBQT+1eBJXSBEdcT+MZbDuYbEt\r\nlC+1Fr6K9XvghYN82oqlHUAoHXJ4q0GNjTZTif0LOkF04yiLueUwO4sNCw2G\r\nu998R8mne5tWkJyN/x+OCexfpuTkYKgagyAWkjXBRfm4pI60IRx7xWbK1/xb\r\niT/Q0pYNdLtjIb9ftNEni2SPV2lCMfumTm9H4Z6839Yx9Z/LboAdEpT6Vvxs\r\nor/VuUD9dU8Ck9wVQyIw/apHbDwTShsOQvyfzKj+imaBY4rwNSaoO2pRwOLV\r\nJAJzm1GYKBtLC2PZTEBoqUKlGFf+yvbJkWTeICYyJqHHKvNKESMccibAvqtO\r\n0troTjTUh2JPUaNUoGNVJaHjQuXWOfgA51s=\r\n=BEk0\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEUCIQDpzyAGmoPs+fp6sPP4LdxUSMDqfKnfCrXywNIgGq8e5QIgcux4C3T2kYcLHkP5oCKBsZSYaierP62xk/xgJCsBNxg="}]},"_npmUser":{"name":"brynjarrr","email":"coinage_trinity_0a@icloud.com"},"directories":{},"maintainers":[{"name":"brynjarrr","email":"coinage_trinity_0a@icloud.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/xchain-client_0.11.1_1648211185652_0.9402683232705804"},"_hasShrinkwrap":false}},"time":{"created":"2022-03-25T12:26:25.594Z","0.11.1":"2022-03-25T12:26:25.832Z","modified":"2022-04-04T20:50:14.200Z"},"maintainers":[{"name":"brynjarrr","email":"coinage_trinity_0a@icloud.com"}],"description":"A specification for a generalised interface for crypto wallets clients, to be used by XChainJS implementations. The client should not have any functionality to generate a key, instead, the `asgardex-crypto` library should be used to ensure cross-chain com","license":"MIT","readme":"# XChainJS Wallet Client Interface\n\nA specification for a generalised interface for crypto wallets clients, to be used by XChainJS implementations. The client should not have any functionality to generate a key, instead, the `asgardex-crypto` library should be used to ensure cross-chain compatible keystores are handled. The client is only ever passed a master BIP39 phrase, from which a temporary key and address is decoded.\n\n### Configuration\n\nInitialise and set up the client to connect to its necessary third-party services to fulfil basic functionality. The third-party services used must be at a minimum to fulfil the wallet functionality, such as displaying balances and sending transactions.\n\nDuring configuration, the following can be passed in:\n\n- Network choice (default is MAINNET)\n- Phrase (mandatory)\n- Service Keys (optional, if null, client will use config defaults or free service limits.)\n\n### Querying\n\nQuerying the client for balances and transaction history. Transaction history is optional.\n\nOptional blockchain-specific queries can be added here, such as Binance Chain market information.\n\n### Transactions\n\nMaking transfers.\n\nOptional blockchain-specific transactions can be added here, such as Binance Chain freeze/unfreeze.\n\n---\n\n# Class Variables\n\n## Client\n\nPublic variable that returns the current client\n\n```ts\npublic client: XChainClient\n```\n\n## Network\n\nPublic variable that returns the current network\n\n```ts\npublic network: Network\n```\n\n## PrivateKey\n\nPrivate variable that retains the private key that was extracted from the phrase during initialisation. The phrase should not be retained.\n\n```ts\nprivate privkey: PrivKey | null = null\n```\n\n## Address\n\nPublic variable that returns the address decoded from the private key during initialisation.\n\n```ts\npublic address: Address\n```\n\n# Config and Setup\n\n## Set Network\n\nUsed to set a type of `Network`, which is either `'mainnet'`, `'stagenet'` or `'testnet'`.\n\n```ts\nsetNetwork(net: Network): XChainClient\n```\n\nReturns the client.\n\n## Set Phrase\n\nUsed to set the master BIP39 phrase, from which the private key is extracted and the address decoded.\n\n```ts\nsetPhrase(phrase: string): address\n```\n\nThe function should store the private key and address, then return the address generated by the phrase.\n\n## Set Service Keys\n\nThe client is expected to know which services it needs, handle errors and have hard-coded sensible defaults if errors. The client should export a type allowing devs to know which services it needs, as well as documentation to explain how to get keys.\n\nIf no key is set, either the service has no API key or the client is expected to stay within node rate limits.\n\nExample:\n\n1. Blockchair (for querying and broadcasting)\n2. Ethplorer (for getting address balances)\n3. EthGasStation (for getting gas prices)\n4. Binance Chain node for Binance queries\n\n- etc\n\nService keys will be passed into constructor by extending `XChainClientParams` interface.\n\nExample BitcoinClient:\n\n```ts\n// extending `XChainClientParams` to provide url and key of API service\ntype BitcoinClientParams = XChainClientParams & {\n  nodeUrl?: string\n  nodeApiKey?: string\n}\n\nclass Client implements BitcoinClient, XChainClient {\n\n  // passing url and key of API service into constructor\n  constructor({ network = Network.Testnet, nodeUrl = '', nodeApiKey = '', phrase }: BitcoinClientParams) {\n    ...\n  }\n}\n\n```\n\n---\n\n# Querying\n\n## Get Explorer URLs\n\nReturns the correctly formatted url string with paths for:\n\n- Addresses\n- Transactions\n\nThe default Explorer URL can be hard-coded, or passed in as a service. It will be provided by `getExplorerUrl`\n\n```ts\ngetExplorerUrl(): string\n```\n\nTo get explorer's URL for an address, use `getExplorerAddressUrl` by passing an `address`.\n\n```ts\ngetExplorerAddressUrl = (address: Address): string\n```\n\nTo get explorer's URL for a transaction, use `getExplorerTxUrl` by passing a transaction ID.\n\n```ts\ngetExplorerTxUrl = (txID: string): string\n```\n\nAll functions should return the correctly formatted url string.\n\n**Example**\n\n```\nhttps://blockchair.com/bitcoin/transaction/d11ff3352c50b1f5c8e2030711702a2071ca0e65457b40e6e0bcbea99e5dc82e\nhttps://blockchair.com/bitcoin/address/19iqYbeATe4RxghQZJnYVFU4mjUUu76EA6\n\nhttps://explorer.binance.org/tx/94F3A6257337052B04F9CC09F657966BFBD88546CA5C23F47AB0A601D29D8979\nhttps://explorer.binance.org/address/bnb1z35wusfv8twfele77vddclka9z84ugywug48gn\n\nhttps://etherscan.io/tx/0x87a4fa498cc48874631eaa776e84a49d28f42f01e22c51ff7cdfe1f2f6772f67\nhttps://etherscan.io/address/0x8eb68e8f207be3dd1ec4baedf0b5c22245cda463\n```\n\n## Get Balance\n\nReturns the balance of an address.\n\n- If address is not passed, gets the balance of the current client address.\n- Optional asset can be passed, in which the query will be specific to that asset, such as ERC-20 token.\n- Returns an array of assets and amounts, with assets in chain notation `CHAIN.SYMBOL-ID`\n\n```ts\ngetBalance(address?: Address, asset?: string): Promise<Balances>\n```\n\nExample of third-party service queries to get balances:\n\n```\nhttps://api.blockchair.com/bitcoin/addresses/balances?addresses=34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo\nhttps://api.ethplorer.io/getAddressInfo/0xb00E81207bcDA63c9E290E0b748252418818c869?apiKey=freekey\nhttps://dex.binance.org/api/v1/account/bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m\n```\n\nExample of returned array:\n\n```json\n[\n  {\n    \"asset\" : \"BTC.BTC\"\n    \"amount\" : 100000000\n  }\n]\n```\n\n## Get Transactions\n\nGets a simplied array of recent transactions for an address.\n\n```ts\n// Defined in xchain-client/src/types.ts\ntype TxHistoryParams = {\n  address: Address // Address to get history for\n  offset?: number // Optional Offset\n  limit?: number // Optional Limit of transactions\n  startTime?: Date // Optional start time\n  asset?: string // Optional asset. Result transactions will be filtered by this asset\n}\n\ngetTransactions(params?: TxHistoryParams): Promise<TxPage>\n```\n\nExample of third party services to help:\n\n```\n// get UTXOS for address\nhttps://api.blockchair.com/bitcoin/outputs?recipient=34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo\n// get tx details for each UTXO\nhttps://api.blockchair.com/bitcoin/dashboards/transactions/ff0bd969cce99b8d8086e452d7b63167fc178680fee796fc742cb14a9a6ef929\n\nhttps://api.ethplorer.io/getAddressTransactions/0xb297cacf0f91c86dd9d2fb47c6d12783121ab780?apiKey=freekey\nhttps://dex.binance.org/api/v1/transactions?address=bnb1jxfh2g85q3v0tdq56fnevx6xcxtcnhtsmcu64m\n```\n\nExample of return:\n\n```json\n[\n  {\n    \"hash\" : \"980D9519CCB39DC02F8B0208A4D181125EE8A2678B280AF70666288B62957DAE\",\n    \"from\" : \"34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo\",\n    \"to\" : 34vRoCGJym3xR7yCVPFHoCNxv4Twseoxp4,\n    \"amount\": 100000000,\n    \"asset\" : \"BTC.BTC\",\n    \"fee\" : 2500,\n    \"memo\" : \"transfer\"\n    \"date\" : \"2020-10-04T06:24:36.548Z\"\n   },\n   {\n    \"hash\" : \"0D9519CCB39DC02F8B0208A4D181125EE8A2678B280AF70666288B62957DAE98\",\n    \"from\" : \"34xp4vRoCGJym3xR7yCVPFHoCNxv4Twseo\",\n    \"to\" : 34vRoCGJym3xR7yCVPFHoCNxv4Twseoxp4,\n    \"amount\": 200000000,\n    \"asset\" : \"BTC.BTC\",\n    \"fee\" : 2500,\n    \"memo\" : \"transfer\"\n    \"date\" : \"2020-10-04T06:24:36.548Z\"\n   },\n]\n```\n\n> Due to the complexity of this function and dependence of third-party services, this function can be omitted in early versions of the client.\n\n---\n\n# Transactions\n\n## Get Fees\n\nThis function calculates and returns the fee object in a generalised way for a simple transfer function.\n\nSince this depends on optional third-party services, sensible defaults should be hardcoded if there are errors.\n\nThe fastest fee rate should be guaranteed next block (1.5x Fast), fast should be 1-2 blocks (1x next block fee rate), average should be 2-3 blocks (0.5x Fast).\n_Don't over-complicate this. PoW blockchains have no guarantees._\n\n- Type should specify the units to display, or if flat fees, simply \"flat\". The client should interpret and display this, such as showing the user the fee rates and their units.\n- Fastest (target of next block)\n- Fast (target of 1-2 blocks)\n- Average (target of 2-3 blocks)\n\nThird party services:\nBitcoin - returns next block feeRate (fast). Use multiples of this to extrapolate to Fastest/Average.\nhttps://api.blockchair.com/bitcoin/stats\n\nEthereum - returns fastest/fast/average\nhttps://ethgasstation.info/api/ethgasAPI.json?api-key=XXAPI_Key_HereXXX\n\n```ts\ngetFees(): Promise<Fees>\n```\n\n**Examples**\n\n```ts\n// Bitcoin (sats/byte)\n{\n  \"type\" : \"byte\"\n  \"fastest\" : 100\n  \"fast\" : 50\n  \"average\" : 20\n}\n// Ethereum (gwei)\n{\n  \"type\" : \"base\"\n  \"fastest\" : 70\n  \"fast\" : 50\n  \"average\" : 40\n}\n// Binance Chain (flat rate)\n{\n  \"type\" : \"base\"\n  \"fastest\" : 37500\n  \"fast\" : 37500\n  \"average\" : 37500\n}\n```\n\n## Transfer\n\nGeneral transfer function that should be signed and broadcast using a third party service.\nThe fee should always be _rate_, which is units per transaction size. The size should be calculated on the fly or hardcoded:\n\n- Bitcoin: 250 bytes is typical, so feeRate of 10 is 10 sats per byte, eg, 2500 sats\n- Ethereum: gwei is standard, so a feeRate of 20 would be interpreted as 20 GWEI\n- Binance Chain: fixed size, so the feeRate is ignored.\n\n**Broadcast URLs**\n\n```\nhttps://api.blockchair.com/{:chain}/push/transaction\nhttps://dex.binance.org/api/v1/broadcast\n```\n\n```ts\nexport type TxParams = {\n  asset: string // BTC.BTC\n  amount: number // in base format (10**8)\n  recipient: address // address\n  feeRate: number // optional feeRate\n  memo: string // optional memo to pass\n}\n\ntransfer(params: TxParams): Promise<TransferResult>\n```\n\nThe function should return the hash of the finalised transaction.\n\n## Chain Specific\n\nChain-specific transactions can be added as well, such as Ethereum `approve()` or Binance Chain `freeze()/unfreeze()`\n\n```ts\ntype ApproveParams = {\n  asset: Asset\n  amount: BaseAmount\n  spender: Address\n}\n\napprove(params: ApproveParams): Promise<TransferResult>\n```\n\nThe function should return the hash of the finalised transaction.\n\n## Purge\n\nWhen a wallet is \"locked\" the private key should be purged in each client by setting it back to null. Also the phrase has to be cleared `this.phrase = ''`\n\n```ts\npurgeClient()\n```\n","readmeFilename":"README.md"}