Tx Protocols

Defines the interface of OCAP query resolver.

Usage

pnpm install @ocap/tx-pipeline

Then:

const TxPipeline = require('@ocap/tx-pipeline');
const NedbAdapter = require('@ocap/statedb-nedb');

const { DecodeTx, VerifyTx, VerifyBlacklist, VerifyReplay, DecodeItx, VerifySignature, ExtractState } = TxPipeline;
// Pre-pipelines
// Check-pipelines: formal
// Verify-pipelines: against state db
// Update-pipelines: change state db

// Create pipeline, this should be defined in `@ocap/tx-protocols`
const pipeline = new TxPipeline('transfer');

// Reuse common pipeline
pipeline.use(DecodeTx);
pipeline.use(VerifyTx);
pipeline.use(VerifyBlacklist);
pipeline.use(VerifyReplay);
pipeline.use(DecodeItx);
pipeline.use(VerifySignature);
pipeline.use(ExtractState({ from: 'tx.from', to: 'senderState' }));

// Attach custom pipeline
pipeline.use(async ({ itx, tx, context, states }, options) => {
  // Do something
});

// Execute transactions
const transaction = {}; // object or base64 encoded string
const adapter = new NedbAdapter({ dbPath: '/path/to/db' });
pipeline
  .execute(pipeline, adapter)
  .then((hash) => {
    console.info('Transaction execution success', hash);
  })
  .catch((err) => {
    console.error('Transaction execution failed', err.message);
  });

Misc

The mysterious delegator/delegatee

Generally, delegator means the party that signed an transaction to allow others to spend his token/asset, and delegatee means the party that received that grant.

In earlier Forge implementation, the Transaction.delegator should be Transaction.delegatee because whether it's delegated transaction or not, the Transaction.from should always point to the account whose balance will be updated on successful transaction execution.

But this will make some transaction protocol logic harder to understand.

• transfer_v2:
  • balance of tx.from will be reduced
  • balance of tx.delegator does not change at all
• exchange_v2: a bit more complicated, let's add details for this later
• acquire_asset_v2:
  • balance of tx.from will be reduced, as payment for purchasing the asset
  • balance of tx.delegator does not change at all
  • owner of minted asset will be set to tx.delegator

The are some inconsistencies in server and client implementation code.

On the server side, delegator must be interpreted as delegatee, but in @ocap/client, delegator is interpreted as delegator. For delegated create-x transactions, the service-fee is charged against tx.from.

How to add a new tx protocol

• Define the itx proto in core/proto/src/tx.proto
• Rebuild proto: cd core/proto && make dep && make build
• Enable the protocol in core/config/lib/default.js and fix the unit test
• Create the protocol file in core/tx-protocols/lib/protocols
• Add receipts logic for the protocol at: core/state/lib/states/tx.js
• Add test case for the protocol: both unit and integration tests
• Add shortcut method in @ocap/client
• Support the protocol in block-explorer if needed: https://github.com/ArcBlock/block-explorer
• Add use cases for the protocol in ocap-playground: https://github.com/blocklet/ocap-playground