npm package: @ocap/tx-protocols
Description: Predefined tx pipeline sets to execute certain type of transactions
Author: wangshijun
Latest version: 1.29.24

# Tx Protocols

Defines the interface of OCAP query resolver.

## Usage

```shell
bun install @ocap/tx-pipeline
```

Then:

```js
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