TypeScript icon, indicating that this package has built-in type declarations

8.31.33 • Public • Published

Adoracore Wallet Service

A Multisig HD Adoracore Wallet Service.


Adoracore Wallet Service facilitates multisig HD wallets creation and operation through a (hopefully) simple and intuitive REST API.

AWS can usually be installed within minutes and accommodates all the needed infrastructure for peers in a multisig wallet to communicate and operate – with minimum server trust.

See adoracore-wallet-client for the official client library that communicates to AWS and verifies its response. Also check adoracore-wallet for a simple CLI wallet implementation that relies on AWS.

AWS is been used in production enviroments for Adoramw Wallet, Adora App wallet and others.

Getting Started

 git clone https://github.com/Rock-n-Block/adora-wallet-core.git
 cd adora-wallet-core/packages/adoracore-wallet-service
 npm install
 npm start

This will launch the AWS service (with default settings) at http://localhost:3232/aws/api.

AWS needs mongoDB. You can configure the connection at aws.config.js

AWS supports SSL and Clustering. For a detailed guide on installing AWS with extra features see Installing AWS.

AWS uses by default a Request Rate Limitation to CreateWallet endpoint. If you need to modify it, check defaults.js' Defaults.RateLimit

Using AWS with PM2

AWS can be used with PM2 with the provided app.js script:

  pm2 start app.js --name "adoracore-wallet-service"

Security Considerations

  • Private keys are never sent to AWS. Copayers store them locally.
  • Extended public keys are stored on AWS. This allows AWS to easily check wallet balance, send offline notifications to copayers, etc.
  • During wallet creation, the initial copayer creates a wallet secret that contains a private key. All copayers need to prove they have the secret by signing their information with this private key when joining the wallet. The secret should be shared using secured channels.
  • A copayer could join the wallet more than once, and there is no mechanism to prevent this. See wallet's confirm command, for a method for confirming copayers.
  • All AWS responses are verified:
    • Addresses and change addresses are derived independently and locally by the copayers from their local data.
    • TX Proposals templates are signed by copayers and verified by others, so the AWS cannot create or tamper with them.

Using SSL

You can add your certificates at the aws.config.js using:

  https: true,
  privateKeyFile: 'private.pem',
  certificateFile: 'cert.pem',
  ////// The following is only for certs which are not
  ////// trusted by nodejs 'https' by default
  ////// CAs like Verisign do not require this
  // CAinter1: '', // ex. 'COMODORSADomainValidationSecureServerCA.crt'
  // CAinter2: '', // ex. 'COMODORSAAddTrustCA.crt'
  // CAroot: '', // ex. 'AddTrustExternalCARoot.crt'

TX proposal life cycle

Tx proposal need to be:

  1. First created via /v?/txproposal -> This will create a 'temporary' TX proposal, returning the object, but not locking the inputs
  2. Then published via /v?/txproposal/:id/publish -> This publish the tx proposal to all copayers, looking the inputs. The TX proposal can be deleted also, after been published.
  3. Then signed via /v?/txproposal/:id/signature for each copayer
  4. Then broadcasted to the p2p network via /v?/txproposal/:id/broadcast

The are plenty example creating and sending proposals in the /test/integration code.

Enabling Regtest Mode for AWS and Adoramw


mongo topology crashes sometimes due to notifications being incompatible in a web browser adoracore-wallet-service/lib/notificationbroadcaster.js Note: If testing on a PC browser, comment out notificationbroadcaster.js to disable notifications.



  1. Add regtest to adoracore.config.json.
"regtest": {
          "chainSource": "p2p",
          "trustedPeers": [
              "host": "",
              "port": 20020
          "rpc": {
            "host": "",
            "port": 20021,
            "username": "adoratest",
            "password": "local321"


  1. Point testnet to http://localhost:3000 in AWS/aws.config.js and set regtestEnabled to true.
blockchainExplorerOpts: {
    btc: {
      livenet: {
        url: 'http://localhost:3000'
      testnet: {
        // set url to http://localhost:3000 here
        url: 'http://localhost:3000',
        // set regtestEnabled to true here
        regtestEnabled: true

Adoramw changes


  1. Comment out content security meta tag in the <head>
// <meta http-equiv="Content-Security-Policy" content="default-src 'self'  ... >

Creating a wallet on regtest network


  1. Set the wallet service URL to
  1. Select Testnet by pressing the slider button.

screen shot 2019-03-06 at 10 50 29 am

Testing on mobile


  • Mobile phone and PC must be connected to the same internet
  • PC desktop ip address for localhost

To find ip address for PC run:

// is equal to localhost
ifconfig | grep "inet " | grep -v
  1. Inside adoramw project root directory run:
npm run apply:adoramw
  1. Enter PC ip address followed by port in the mobile phone browser:
  1. Set wallet service url to PC ip address /aws/api when creating a new wallet


Note: all currency amounts are in units of satoshis (1/100,000,000 of a bitcoin).


In order to access a wallet, clients are required to send the headers:


Identity is the Peer-ID, this will identify the peer and its wallet. Signature is the current request signature, using requestSigningKey, the m/1/1 derivative of the Extended Private Key.

See Adoracore Wallet Client for implementation details.

GET Endpoints

/v1/wallets/: Get wallet information


/v1/txhistory/: Get Wallet's transaction history

Optional Arguments:

  • skip: Records to skip from the result (defaults to 0)
  • limit: Total number of records to return (return all available records if not specified).


  • History of incoming and outgoing transactions of the wallet. The list is paginated using the skip & limit params. Each item has the following fields:
  • action ('sent', 'received', 'moved')
  • amount
  • fees
  • time
  • addressTo
  • confirmations
  • proposalId
  • creatorName
  • message
  • actions array ['createdOn', 'type', 'copayerId', 'copayerName', 'comment']

/v2/txproposals/: Get Wallet's pending transaction proposals and their status


/v4/addresses/: Get Wallet's main addresses (does not include change addresses)

Optional Arguments:

  • ignoreMaxGap: [false] Ignore checking less that 20 unused addresses (BIP44 GAP)


/v1/balance/: Get Wallet's balance


  • totalAmount: Wallet's total balance
  • lockedAmount: Current balance of outstanding transaction proposals, that cannot be used on new transactions.
  • availableAmount: Funds available for new proposals.
  • totalConfirmedAmount: Same as totalAmount for confirmed UTXOs only.
  • lockedConfirmedAmount: Same as lockedAmount for confirmed UTXOs only.
  • availableConfirmedAmount: Same as availableAmount for confirmed UTXOs only.
  • byAddress array ['address', 'path', 'amount']: A list of addresses holding funds.
  • totalKbToSendMax: An estimation of the number of KiB required to include all available UTXOs in a tx (including unconfirmed).

/v1/txnotes/:txid: Get user notes associated to the specified transaction


  • The note associated to the txid as a string.

/v1/fiatrates/:code: Get the fiat rate for the specified ISO 4217 code

Optional Arguments:

  • provider: An identifier representing the source of the rates.
  • ts: The timestamp for the fiat rate (defaults to now).


  • The fiat exchange rate.

POST Endpoints

/v1/wallets/: Create a new Wallet

Required Arguments:

  • name: Name of the wallet
  • m: Number of required peers to sign transactions
  • n: Number of total peers on the wallet
  • pubKey: Wallet Creation Public key to check joining copayer's signatures (the private key is unknown by AWS and must be communicated by the creator peer to other peers).


  • walletId: Id of the new created wallet

/v1/wallets/:id/copayers/: Join a Wallet in creation

Required Arguments:

  • walletId: Id of the wallet to join
  • name: Copayer Name
  • xPubKey - Extended Public Key for this copayer.
  • requestPubKey - Public Key used to check requests from this copayer.
  • copayerSignature - Signature used by other copayers to verify that the copayer joining knows the wallet secret.


  • copayerId: Assigned ID of the copayer (to be used on x-identity header)
  • wallet: Object with wallet's information

/v3/txproposals/: Add a new temporary transaction proposal

Required Arguments:

  • toAddress: RCPT Bitcoin address.
  • amount: amount (in satoshis) of the mount proposed to be transfered
  • proposalsSignature: Signature of the proposal by the creator peer, using proposalSigningKey.
  • (opt) message: Encrypted private message to peers.
  • (opt) feePerKb: Use an alternative fee per KB for this TX.
  • (opt) excludeUnconfirmedUtxos: Do not use UTXOs of unconfirmed transactions as inputs for this TX.
  • BCH addresses need to be cashaddr without prefix.


/v2/txproposals/:id/publish: Publish the previously created temporary tx proposal


/v3/addresses/: Request a new main address from wallet . (creates an address on normal conditions)


/v1/txproposals/:id/signatures/: Sign a transaction proposal

Required Arguments:

  • signatures: All Transaction's input signatures, in order of appearance.


/v1/txproposals/:id/broadcast/: Broadcast a transaction proposal


/v1/txproposals/:id/rejections: Reject a transaction proposal


/v1/addresses/scan: Start an address scan process looking for activity.

Optional Arguments:

  • includeCopayerBranches: Scan all copayer branches following BIP45 recommendation (defaults to false).

/v1/txconfirmations/: Subscribe to receive push notifications when the specified transaction gets confirmed

Required Arguments:

  • txid: The transaction to subscribe to.

PUT Endpoints

/v1/txnotes/:txid/: Modify a note for a tx

DELETE Endpoints

/v1/txproposals/:id/: Deletes a transaction proposal. Only the creator can delete a TX Proposal, and only if it has no other signatures or rejections


/v1/txconfirmations/:txid: Unsubscribe from transaction txid and no longer listen to its confirmation

Push Notifications

Recomended to complete config.js file:

POST Endpoints

/v1/pushnotifications/subscriptions/: Adds subscriptions for push notifications service at database

DELETE Endpoints

/v2/pushnotifications/subscriptions/: Remove subscriptions for push notifications service from database


See CONTRIBUTING.md on the main adoracore repo for information about how to contribute.


Code released under the MIT license.

Copyright 2013-2019 Adora.

Package Sidebar


npm i @adora-wallet/adoracore-wallet-service

Weekly Downloads






Unpacked Size

3.12 MB

Total Files


Last publish


  • murmuri