@cruxpay/js-sdk

CruxPay is a protocol which aims to link any blockchain address to a human-readable name, and let users interact with each other and dApps with ease.

Adding cruxpay-sdk.js

First you need to get cruxpay sdk into your project. This can be done using the following methods:

npm: npm install @cruxpay/js-sdk
pure js: link the cruxpay-sdk-dom.js

SDK Initialisation:

To initialize the sdk, you need to minimally pass a javascript object with following details:-

walletClientName
- walletClientName is the key which identifies the wallet specific configurations stored in gaiaHub like
  1. Subdomain Registrar Information
  2. BNS(BlockStack Name Service) Node
  3. Currency symbol map of your wallet
- To help you get started, you can use cruxdev as the value which is already configured for our dev test users. It has 5 pre-registered crypto symbols for a fast start. You can contact us at telegram channel for registration of your own walletClientName.
privateKey (optional)
- Required to re-initialise the CruxClient with same user across different devices.
- For clients using HD derivation paths, recommended to use the path (m/889'/0'/0') for CruxPay keypair node derivation with respect to account indices.

**Note:** Cruxprotocol JS SDK is case insensetive for cryptocurrency symbols and will always output lowercase symbols.

Example below shows how to a cruxClient instance. These are the SDK Operation exposed.

let cruxClientOptions = {
    walletClientName: 'cruxdev',
    privateKey: "6bd397dc89272e71165a0e7d197b280c7a88ed5b1e44e1928c25455506f1968f"  // (optional parameter)
}

let cruxClient = new CruxClient(cruxClientOptions);

That's it! now you can use the cruxClient object to perform operations defined in SDK Operation.

cruxClient.getCruxIDState().then((cruxIDState) => {
    console.log(cruxIDState);
})

Wallet clients are encouraged to surface the respective ERROR_CODE of the CruxClientError to their Users with any custom error messages. This will help in debugging any issues with the functionality.

Refer error-handling.md for more information on Error handling.

SDK Operation

isCruxIDAvailable(cruxID)
- Description: Helps to check if a particular CruxID is available to be registered.
- Params:
  - subdomain part of CruxID
- Returns: Promise resolving to a boolean indicating whether a particular Crux ID is available for registration.
getAssetMap()
- Description: Get Wallet's asset map with currency symbols as the keys and asset object as the value.
- Params: None
- Returns: Promise resolving to IResolvedClientAssetMapping which has symbols and asset objects.

registerCruxID(cruxID)

Description: Reserves/registers the cruxID for the user. The user can link any blockchain address to his CruxID immediately after registration using putAddressMap.
Params:
- subdomain part of CruxID

Returns: Promise resolving on successful call to the registrar.

const sampleAddressMap: IAddressMapping = {
  'BTC': {
      addressHash: '1F1tAaz5x1HUXrCNLbtMDqcw6o5GNn4xqX'
  },
  'ETH': {
      addressHash: '0x7cB57B5A97eAbe94205C07890BE4c1aD31E486A8'
  },
}

// Advised to pipe the method putAddressMap to registerCruxID call

await cruxClient.registerCruxID("bob")
  .then(() => {
      return cruxClient.putAddressMap(sampleAddressMap)
          .catch((addressUpdationError) => {
              // Handling addressUpdation error
          })
  })
  .catch((registrationError) => {
      // Handling registration error
  })

resolveCurrencyAddressForCruxID(cruxID, walletCurrencySymbol)
- Description: Helps to lookup a mapped address for a currency of any CruxID if its marked publically accessible.
- Params:
  - complete CruxID of a user whose address you want to fetch
  - walletCurrencySymbol wallet symbol of currency whose address you want to fetch.
- Returns: Promise resolving to IAddress for that symbol of currency if available.
getAddressMap()
- Description: Get back the current publicly registered address json
- Params: None
- Returns: Promise resolving to IAddressMapping
putAddressMap(newAddressMap)
- Description: Helps to update 2 things:-
  - publish/change list of publicly accessible currency addresses.
  - change the value of addressHash and/or secIdentifier to another one.
- Note: The addresses are now publicly linked and can be resolved. To get which currencies can be part of newAddressMap please call getAssetMap().
- Params:
  - newAddressMap of type IAddressMapping has modified map has symbols and addresses a user wants to publically expose with CruxID.
- Returns: Promise resolving to {success: IPutAddressMapSuccess, failures: IPutAddressMapFailures}
getCruxIDState()
- Description: Returns details of the current registered CruxID(if any) for this instance of the user wallet and its registration status
- Params: None
- Returns: Promise resolving to CruxIDState