@ixo/client-sdk

ixo-client SDK

A complete package of client software for developing client applications which connect to the ixo software stack and build on the Internet of Impact.

The ixo-Client SDK has 5 core components:

• ixo-Crypto tools: Generates mnemonic seeds, decentralised identitifiers, cryptographic key pairs and provides message signing methods.

• ixo-Blockchain client: Composes, signs (with secp256k1)and broadcasts messages to ixo-protocol blockchains. Gets data directly from ixo-blockchain RPC endpoints.

• ixo-BlockSync client: Gets data from the ixo-BlockSync index database, with standard queries.

• ixo-CellNode client: Composes messages, signs (with ED25519), writes to an ixo-CellNode private REST endpoint for did-authentication, and reads from the private endpoint with did-authentication access control.

• (ixo-Identity client: Coming soon)

Note: This documentation is work in progress.
The functionality of the SDK listed below is already available. Don't hesitate to try them out or even to check out the source (it really is simple).
Your feedback is welcome -- please don't hesitate to send issues & submit PRs.

Usage

const {
    crypto,
    makeBlockchainClient,
    makeBlocksyncClient,
    makeCellNodeClient,
}
    = require('@ixo/client-sdk')

const
    blockchainCli = makeBlockchainClient('<chain url>'),
    blocksyncCli = makeBlocksyncClient('<blocksync url>'),
    cellnodeCli = makeCellnodeClient('<cell node url>'),
    anotherCellnodeCli = makeCellnodeClient('<another cell node url>')

Crypto tools

• generateMnemonic([entropy])

  Returns a randomly generated mnemonic.

    const mnemonic = crypto.generateMnemonic()
  

  In environments that don't support random byte generation natively, you will need to pass a custom entropy object yourself. React Native example:

    const {randomBytes} = require('react-native-randombytes')
  
    const mnemonic = crypto.generateMnemonic(randomBytes(16))
  

• deriveAddress(mnemonic)

  Returns a BEP32 account address, using the given mnemonic as the seed. This is the account address on any ixo or Cosmos blockchain.

• deriveECKeyPair(mnemonic)

  Returns a key-pair generated by Bitcoin's SECP256k1 algorithm, using the given mnemonic as the seed.

• signEC(message, privateKey)

  Signs a given message with the client's SECP256k1 private key, to prepare this for broadcast to any Cosmos SDK-based blockchain. Returns the signature value.

• deriveDidDoc(mnemonic)

  Returns the DID document object for a given DID, generated using the given mnemonic as the seed. See the Sovrin DID package on NPM for the return schema. See the Sovrin protocol docs on the DID Method.

• deriveAgentAddress(verifyKey)

  Returns a Cosmos-SDK account address using the given verify key (from a DID) as the seed. This is the address for the ixo agent.

The ixo-blockchain client

• raw(url, opts)

  Make a direct API call to the blockchain.
  Check out the Cosmos REST API docs here: https://cosmos.network/rpc/v0.37.9

  Examples:

  const {body: balances} = cli.raw('/bank/balances/' + someAddress)
  
  const {body: block} = cli.raw('/blocks/latest')
  

• getAccounts(address)

  Gets the accounts associated with a given address.

• makeStdMsg(input)

  Formats any unsigned message into the format required for validation by Tendermint, using the given input. Input example:

  {
      msgs: [
          {
              type: 'treasury/MsgSend',
              value: {
                  from_did: 'did:ixo:U7GK8p8rVhJMKhBVRCJJ8c',
                  to_did_or_addr: 'did:ixo:4XJLBfGtWSGKSz4BeRxdun',
                  amount: [{amount: '100'), denom: 'uixo'}],
              }
          }
      ],
      chain_id: '<chain id>',
      fee: {amount: [{amount: '5000', denom: 'uixo'}], gas: '200000'},
      memo: '',
      account_number: '<a valid account number>',
      sequence: '<a valid sequence>',
  }
  

  See messages.md for a catalogue of valid message types and values.

• broadcast(signedTx)

  Sends a signed message to an ixo-blockchain node RPC endpoint.

The ixo-Blocksync client

• raw(url, opts)

  Makes direct Rest API calls to the blocksync to query and get indexed blockchain data. Check out the Blocksync API for available endpoints.

  Examples:

  const {body: {signed_data, fee}}
    = cli.raw('/api/sign_data', {method: 'POST', body: { ... }})
  
  const {body: projectList} = cli.raw('/api/project/listProjects')
  

• ping()

  Ping the BlockSync service to check if this is working properly.

• getStats()

• registerUser(didDoc)

  Register a user with the given DID.

• getDidDoc(did)

  Returns the full DID document for a given agent or entity DID.

• listProjects(senderDid)

  Lists all available projects which have been created using the given DID.

• getProject(did)

  Get details of a specific project by its Entity DID.

  Example return value:

  {
    statusCode: 200,
    headers: { ... },
    body: {
      data: {
        claimStats: { currentSuccessful: 0, currentRejected: 0 },
        agentStats: {
          evaluators: 0,
          evaluatorsPending: 0,
          serviceProviders: 0,
          serviceProvidersPending: 0,
          investors: 0,
          investorsPending: 0
        },
        socialMedia: {
          facebookLink: '',
          instagramLink: '',
          twitterLink: '',
          webLink: ''
        },
        ixo: { totalStaked: 0, totalUsed: 0 },
        sdgs: [ 10 ],
        '@type': 'Project',
        name: 'WEDO GLOBAL WEBSITE',
        description: 'WEDO GLOBAL specializes in designing and ...',
        image: 'https://pds_pandora.ixo.world/public/7bkzqb0ofz6kk5f4r9f',
        imageDescription: 'WEDO GLOBAL, a social enterprise ...',
        brand: 'WEDO GLOBAL',
        logo: 'https://pds_pandora.ixo.world/public/tqsgfvi2zikk5f5ide',
        location: 'HK',
        '@context': 'https://schema.ixo.foundation/entity:2383r9riuew',
        entitySchemaVersion: '1.0.0',
        relayerNode: 'did:sov:Rmb6Rd1CU6k74FM2xzy6Do',
        startDate: 'Invalid date',
        endDate: 'Invalid date',
        status: 'Live',
        stage: 'Delivery',
        version: { versionNumber: '1', effectiveDate: '2021-01-05T00:00:00.000Z' },
        terms: { '@type': 'OnceOffFee', paymentTemplateId: '1' },
        privacy: { pageView: 'Public', entityView: 'Visible', credentials: [] },
        creator: {
          id: 'did:sov:Pxyq1FuSJ3QK4FqJ8WzsNb',
          displayName: 'Tom Chan',
          logo: 'https://pds_pandora.ixo.world/public/l73zj2bn9kokk5f88bx',
          location: 'HK',
          email: '[e-mail]',
          website: 'https://socialenterprise.org.hk',
          mission: 'service',
          credentialId: 'did:sov:LRGVKuk1Lmi16SUBWyXPAC'
        },
        owner: {
          id: 'did:sov:BnVm8NhqSoZfmseZoHNTNi',
          displayName: 'Eva Wong',
          logo: 'https://pds_pandora.ixo.world/public/yxb018gxlhqkk5f8q9y',
          location: 'HK',
          email: '[e-mail]',
          website: 'https://www.wedoglobal.com/zh-TW',
          mission: '提倡多元文化教育'
        },
        ddoTags: [
          { category: 'Project Type', tags: [ 'Index' ] },
          { category: 'SDG', tags: [ 'SDG10 – Reduced Inequalities' ] },
          { category: 'Stage', tags: [ 'Delivery' ] },
          { category: 'Sector', tags: [ 'IDCC' ] }
        ],
        displayCredentials: {
          '@context': 'https://www.w3.org/2018/credentials/v1',
          items: []
        },
        page: { cid: 'wj0whzpzqdrkk5f9ujb', version: '1.0.0' },
        entityClaims: {
          '@context': 'https://schema.ixo.world/claims:3r08webu2eou',
          items: [
            {
              '@id': 'did:ixo:LjBRtnchDzEKyAU2v7LiDv',
              visibility: 'Public',
              title: 'ToC',
              description: 'Theory of Change Description',
              targetMin: 1,
              targetMax: 100,
              startDate: '2021-01-20T00:00:00.000Z',
              endDate: '2021-02-19T00:00:00.000Z',
              goal: 'test 20201223',
              agents: [],
              claimEvaluation: [],
              claimApproval: [],
              claimEnrichment: []
            },
          ]
        },
        linkedEntities: [],
        fees: {
          '@context': 'https://schema.ixo.world/fees/ipfs3r08webu2eou',
          items: []
        },
        stake: {
          '@context': 'https://schema.ixo.world/staking/ipfs3r08webu2eou',
          items: []
        },
        nodes: {
          '@context': 'https://schema.ixo.world/nodes/ipfs3r08webu2eou',
          items: [
            {
              '@type': 'CellNode',
              id: '1',
              serviceEndpoint: 'https://pds_pandora.ixo.world'
            }
          ]
        },
        funding: {
          '@context': 'https://schema.ixo.world/funding/ipfs3r08webu2eou',
          items: []
        },
        keys: { '@context': 'https://www.w3.org/ns/did/v1', items: [] },
        service: [],
        data: [],
        createdOn: '2021-01-20T12:48:35.000Z',
        createdBy: 'did:sov:Pxyq1FuSJ3QK4FqJ8WzsNb',
        nodeDid: 'did:ixo:Sdjhti1ywgWgQJqtgYrGzJ',
        claims: [],
        agents: []
      },
      _id: '600826ab6f0909001aad49ac',
      txHash: '96a55adb2d58ab9c2ece81298dd6cc1831797e5f392739ed2424cb9378849e55',
      senderDid: 'did:sov:Pxyq1FuSJ3QK4FqJ8WzsNb',
      projectDid: 'did:ixo:LqmfEB75Dnqzz7AiYfRFXA',
      pubKey: 'BpD7FhAKnt6NfDaidEg8kWzuqRAgbrVAo6QZB4NZgyVr',
      __v: 0
    }
  }
  

The ixo-CellNode client

• raw(url, opts)

  Make direct Rest API calls to an entity's CellNode URI endpoint.
  Requires DID-Authentication and performs stateless validation of messages.
  See the CellNode API docs for available endpoints.

• entity.create(data, signature)

• entity.update(data, signature)

• entity.fund(data, signature)

• entity.createPublic(base64Content)

• entity.fetchPublic(key)

• agent.create(data, signature)

• agent.list(data, signature)

• agent.updateStatus(data, signature)

• claim.create(data, signature)

• claim.evaluate(data, signature)

• claim.list(data, signature)