README
Tx Protocols
Defines the interface of OCAP query resolver.
Usage
yarn add @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
delegator/delegatee
The mysterious 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
- balance of
exchange_v2
: a bit more complicated, let's add details for this lateracquire_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
- balance of
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