@sodazone/ocelloids

Ocelloids Core Module

The Ocelloids Core Module provides base abstractions, reactive operators, and pallet-independent functionality.

Layout

The packages/core module source folder is structured as follows:

Directory	Description
apis	Multi-chain APIs
client	Alternative light client connector
configuration	Configuration
converters	Chain data type conversions
observables	Reactive emitters
operators	Reactive operators
subjects	Reactive subjects
types	Extended types

Usage

Refer to the SDK documentation.

Additionally, check out the examples/ folder for example applications.

Logging

Ocelloids supports configuring debug logger outputs to aid in development.

The table below displays the available loggers and their descriptions:

Logger Name	Description
oc-ops-mongo-filter	Prints the transformed object data in "named primitive" format before filtering in the mongo-filter operator.
oc-ops-flatten	Prints extrinsic call flattening details.
oc-blocks	Prints the current block number in block-related observables.
oc-substrate-apis	Prints initialisation data of Substrate APIs.

To enable debugging logs for a specific category, use the DEBUG environment variable with the corresponding logger name.

For example, to enable debugging logs for the "oc-ops-mongo-filter" category, you can run the following command:

DEBUG=oc-ops-mongo-filter yarn filter-fee-events

You can specify multiple logger names separated by a comma, as shown in the example below:

DEBUG=oc-ops-mongo-filter,oc-blocks yarn filter-fee-events

These loggers provide valuable information that can assist with data filtering and tracking contextual information.

Custom Methods and Types

When instantiating the APIs, you have the flexibility to register custom RPC and runtime methods, as well as define custom types for the networks you're interacting with.

Here's a simple demonstration:

import { WsProvider } from '@polkadot/api';

import { SubstrateApis } from '@sodazone/ocelloids';

const apis = new SubstrateApis({
  network: {
    provider: new WsProvider('wss://my-custom-rpc.io'),
    rpc: {
      // custom RPC methods
    },
    runtime: {
      // custome runtime methods
    },
    types: [
      {
        "minmax": [
          0,
          null
        ],
        types: {
          // custom types
        }
      }
    ]
  },
});

For more detailed information on extending types and methods in the API, please refer to the Polkadot.js documentation on Extending Types and Custom RPC.

You can also explore a practical example of how custom methods and types are registered in the watch-contracts example application.

Nested Calls Flattener

The Flattener, a specialized helper class, recursively extracts all nested calls from a given extrinsic. It assigns the subset of events in that extrinsic corresponding to each call and maps any execution errors to the extracted calls. This is particularly useful when dealing with extrinsics containing nested batch, multisig, or proxy calls.

The Flattener is utilized within the flattenCalls operator and is also exported for external use, such as in an observer handler:

// Flatten and log extrinsic 8695536-2 on Rococo ([Subscan link](https://rococo.subscan.io/extrinsic/8695536-2))
apis.rx.polkadot.pipe(
  blocksInRange(8695536, 1),
  extractTxWithEvents(), // Simply extract TxWithIdAndEvents without flattening or filtering
  filter(tx => tx.extrinsic.extrinsicId === '8695536-2') // Filter for only the `forceBatch` extrinsic
).subscribe(tx => {
  // Initialise flattener and flatten nested calls
  const flattener = new Flattener(tx);
  flattener.flatten();
  const calls = flattener.flattenedCalls;
  calls.forEach(c => {
    console.log('==============================================================================');
    console.log('Extrinsic:', c.extrinsic.method.toHuman());
    console.log('Events:', c.events.map(e => e.toHuman()));
    console.log('Execution results:', c.dispatchError ? c.dispatchError.toHuman() : 'Success');
  });
});

You will see the following output:

Flattened calls - click to expand

============================
Extrinsic: {
  args: { calls: [ [Object], [Object], [Object] ] },
  method: 'forceBatch',
  section: 'utility'
}
Events: [
  {
    method: 'BatchCompleted',
    section: 'utility',
    index: '0x1801',
    data: {}
  },
  {
    method: 'Deposit',
    section: 'balances',
    index: '0x0407',
    data: {
      who: '5GEse7uuvXbkNFi6o8WeaL1S5omApVB4D9oFjEm7791BuLXW',
      amount: '121,680'
    }
  },
  {
    method: 'Deposit',
    section: 'balances',
    index: '0x0407',
    data: {
      who: '5Ef7wVYfsmCiCNfDzzFFt9zpz2tPgZ114s5NueMkVCjj7ZSQ',
      amount: '100,384,984'
    }
  },
  {
    method: 'TransactionFeePaid',
    section: 'transactionPayment',
    index: '0x2100',
    data: {
      who: '5GEse7uuvXbkNFi6o8WeaL1S5omApVB4D9oFjEm7791BuLXW',
      actualFee: '100,384,984',
      tip: '0'
    }
  },
  {
    method: 'ExtrinsicSuccess',
    section: 'system',
    index: '0x0000',
    data: { dispatchInfo: [Object] }
  }
]
Execution results: Success
============================
Extrinsic: {
  args: { remark: '0x540d0053ef00540d00ff0c00975e005e3800540d' },
  method: 'remark',
  section: 'system'
}
Events: [
  {
    method: 'ItemCompleted',
    section: 'utility',
    index: '0x1803',
    data: {}
  }
]
Execution results: Success
============================
Extrinsic: {
  args: { calls: [ [Object], [Object], [Object] ] },
  method: 'forceBatch',
  section: 'utility'
}
Events: [
  {
    method: 'BatchCompletedWithErrors',
    section: 'utility',
    index: '0x1802',
    data: {}
  },
  {
    method: 'ItemCompleted',
    section: 'utility',
    index: '0x1803',
    data: {}
  }
]
Execution results: Success
============================
Extrinsic: {
  args: {
    dest: { Id: '5FLPbcLRQBqU3UCaNJCDF4bGify3Eor2dj3f4kxJq3szgeC5' },
    value: '2,000,000,000,000'
  },
  method: 'transferKeepAlive',
  section: 'balances'
}
Events: [
  {
    method: 'Transfer',
    section: 'balances',
    index: '0x0402',
    data: {
      from: '5GEse7uuvXbkNFi6o8WeaL1S5omApVB4D9oFjEm7791BuLXW',
      to: '5FLPbcLRQBqU3UCaNJCDF4bGify3Eor2dj3f4kxJq3szgeC5',
      amount: '2,000,000,000,000'
    }
  },
  {
    method: 'ItemCompleted',
    section: 'utility',
    index: '0x1803',
    data: {}
  }
]
Execution results: Success
============================
Extrinsic: {
  args: {
    dest: { Id: '5GEse7uuvXbkNFi6o8WeaL1S5omApVB4D9oFjEm7791BuLXW' },
    value: '1,000,000,000,000,000,000,000'
  },
  method: 'transferKeepAlive',
  section: 'balances'
}
Events: [
  {
    method: 'ItemFailed',
    section: 'utility',
    index: '0x1804',
    data: { error: [Object] }
  }
]
Execution results: { Arithmetic: 'Underflow' }
============================
Extrinsic: {
  args: {
    dest: { Id: '5HKLQkkz5ifs43BRHmZKe5DevTYY1iRiNp6CPHkM8sv3ZXPb' },
    value: '3,000,000,000,000'
  },
  method: 'transferKeepAlive',
  section: 'balances'
}
Events: [
  {
    method: 'Transfer',
    section: 'balances',
    index: '0x0402',
    data: {
      from: '5GEse7uuvXbkNFi6o8WeaL1S5omApVB4D9oFjEm7791BuLXW',
      to: '5HKLQkkz5ifs43BRHmZKe5DevTYY1iRiNp6CPHkM8sv3ZXPb',
      amount: '3,000,000,000,000'
    }
  },
  {
    method: 'ItemCompleted',
    section: 'utility',
    index: '0x1803',
    data: {}
  }
]
Execution results: Success
============================
Extrinsic: {
  args: { remark: '0x90530053ef00905300ff0c00975e005e38009053' },
  method: 'remark',
  section: 'system'
}
Events: [
  {
    method: 'Withdraw',
    section: 'balances',
    index: '0x0408',
    data: {
      who: '5GEse7uuvXbkNFi6o8WeaL1S5omApVB4D9oFjEm7791BuLXW',
      amount: '100,506,664'
    }
  },
  {
    method: 'ItemCompleted',
    section: 'utility',
    index: '0x1803',
    data: {}
  }
]
Execution results: Success