@ocap/tx-protocols 1.6.3 → 1.6.10

package/README.md

@@ -49,3 +49,39 @@ pipeline
     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

package/lib/execute.js

@@ -1,57 +1,124 @@
 /* eslint-disable consistent-return */
+const get = require('lodash/get');
+const pick = require('lodash/pick');
+const omit = require('lodash/omit');
 const camelCase = require('lodash/camelCase');
+const Error = require('@ocap/util/lib/error');
 const { Runner, pipes } = require('@ocap/tx-pipeline');
 
 const getTxName = (typeUrl) => camelCase(typeUrl.split(':').pop());
 
+const flushEvents = (context, extra = {}) => {
+  (context.events || []).forEach((e) => {
+    context.statedb[e.table].emit(e.name, e.data, { ...e.ctx, ...extra });
+  });
+  context.events = [];
+};
+
+const shouldPersistTx = (err) => !err || get(err, 'props.persist');
+
 module.exports = ({ filter, runAsLambda }) => {
   // pipeline before executing the transaction
   const pre = new Runner();
   pre.use(pipes.DecodeTx);
-  pre.use(pipes.VerifyTx);
-  pre.use(pipes.VerifyReplay({ filter, key: 'txHash' }));
   pre.use(pipes.DecodeItx);
+  pre.use(pipes.VerifyTx);
+  pre.use(pipes.VerifyServiceFee);
+
+  pre.use(async (context, next) => {
+    if (filter.has(context.txHash)) {
+      // Since bloom-filters may give false positive, we need to check for statedb if replay detected
+      const exist = await context.statedb.tx.get(context.txHash, context);
+      if (exist) {
+        return next(new Error('DUPLICATE_TX', 'Can not execute duplicate transaction'));
+      }
+    }
+
+    filter.add(context.txHash);
+    return next();
+  });
+
   pre.use(pipes.VerifyTxSize);
   pre.use(pipes.VerifySignature);
 
-  // pipeline after executing the transaction
-  const post = new Runner();
-  post.use(async (context, next) => {
-    // TODO: do we want to save failed transactions here, if we do, just attach an error handling pipe
-    const tx = context.states.tx.create(context);
-    await context.statedb.tx.create(tx.hash, tx, context);
+  const execute = async (context, protocols, isRetrySupported = false) =>
+    new Promise((resolve, reject) => {
+      pre.run(context, (err) => {
+        if (err) {
+          if (process.env.NODE_ENV !== 'test') {
+            console.error('Failed to prepare transaction', err);
+          }
+          return reject(err);
+        }
 
-    next();
-  });
+        const name = getTxName(context.txType);
+        const protocol = protocols[name];
+        if (!protocol) {
+          return reject(new Error('UNSUPPORTED_TX', `Unsupported tx type ${context.txType}`));
+        }
 
-  const execute = async (context, protocols) => {
-    await pre.runAsync(context);
+        // eslint-disable-next-line no-shadow
+        protocol.run(context, async (err) => {
+          // we should only flush events when retry is not supported
+          // otherwise the outer caller should handle these 2
+          if (shouldPersistTx(err) && isRetrySupported === false) {
+            const txState = context.states.tx.create(context, err ? err.code || 'INTERNAL' : 'OK');
+            try {
+              await context.statedb.tx.create(txState.hash, txState, context);
+            } catch (e) {
+              console.error('Failed to save transaction to statedb', e);
+            }
 
-    const name = getTxName(context.txType);
-    const protocol = protocols[name];
-    if (!protocol) {
-      throw new Error('UNSUPPORTED_TX', `Unsupported tx type ${context.txType}`);
-    }
+            flushEvents(context, { txState });
+          }
 
-    await protocol.runAsync(context);
-    await post.runAsync(context);
+          // after executing the transaction
+          if (err) {
+            // console.error('Failed to execute transaction', err);
+            return reject(err);
+          }
 
-    return context;
-  };
+          resolve(context);
+        });
+      });
+    });
 
   if (typeof runAsLambda === 'function') {
-    return (context, protocols) =>
-      new Promise((resolve, reject) => {
-        runAsLambda(async (txn) => {
-          Object.defineProperty(context, 'txn', { value: txn });
+    return async (context, protocols) => {
+      let ctx = null;
+      let error = null;
+
+      try {
+        await runAsLambda((txn) => {
+          // create a new context each time in case we are retrying
+          ctx = pick(context, ['txBase64', 'statedb', 'config', 'states']);
+          Object.defineProperty(ctx, 'txn', { value: txn });
+          return execute(ctx, protocols, true);
+        });
+      } catch (err) {
+        error = err;
+      } finally {
+        if (shouldPersistTx(error)) {
           try {
-            await execute(context, protocols);
-            resolve(context);
+            const txState = context.states.tx.create(ctx, error ? error.code || 'INTERNAL' : 'OK');
+            flushEvents(ctx, { txState });
+            await runAsLambda(async (txn) => {
+              const newCtx = { ...omit(ctx, ['txn']), txn };
+              await context.statedb.tx.create(txState.hash, txState, newCtx);
+              flushEvents(newCtx, { txState });
+            });
           } catch (err) {
-            reject(err);
+            console.error('failed to save invalid transaction to statedb', err);
           }
-        });
-      });
+        }
+      }
+
+      if (error) {
+        throw error;
+      }
+
+      return ctx;
+    };
   }
 
   return execute;

package/lib/index.js

@@ -1,26 +1,44 @@
-const EventEmitter = require('events');
 const states = require('@ocap/state');
 
-const transfer = require('./protocols/trade/transfer');
-const exchange = require('./protocols/trade/exchange');
+const transferV2 = require('./protocols/trade/transfer-v2');
+const transferV3 = require('./protocols/trade/transfer-v3');
+const exchangeV2 = require('./protocols/trade/exchange-v2');
 const declare = require('./protocols/account/declare');
 const migrate = require('./protocols/account/migrate');
 const delegate = require('./protocols/account/delegate');
 const revokeDelegate = require('./protocols/account/revoke-delegate');
 const createAsset = require('./protocols/asset/create');
 const updateAsset = require('./protocols/asset/update');
-const poke = require('./protocols/misc/poke');
+const createFactory = require('./protocols/factory/create');
+const acquireAssetV2 = require('./protocols/asset/acquire-v2');
+const acquireAssetV3 = require('./protocols/asset/acquire-v3');
+const mintAsset = require('./protocols/asset/mint');
+const createToken = require('./protocols/token/create');
+const stake = require('./protocols/governance/stake');
+const revokeStake = require('./protocols/governance/revoke-stake');
+const claimStake = require('./protocols/governance/claim-stake');
+const depositTokenV2 = require('./protocols/token/deposit-v2');
+const withdrawTokenV2 = require('./protocols/token/withdraw-v2');
+const createRollup = require('./protocols/rollup/create');
+const updateRollup = require('./protocols/rollup/update');
+const joinRollup = require('./protocols/rollup/join');
+const leaveRollup = require('./protocols/rollup/leave');
+const pauseRollup = require('./protocols/rollup/pause');
+const resumeRollup = require('./protocols/rollup/resume');
+const createRollupBlock = require('./protocols/rollup/create-block');
+const claimBlockReward = require('./protocols/rollup/claim-reward');
+const migrateRollupContract = require('./protocols/rollup/migrate-contract');
+const migrateRollupToken = require('./protocols/rollup/migrate-token');
 
 const executor = require('./execute');
 
 const createExecutor = ({ filter, runAsLambda }) => {
-  const events = new EventEmitter();
-  const emit = (...args) => events.emit(...args);
-
   const protocols = {
     // trade
-    transfer,
-    exchange,
+    transfer: transferV2,
+    transferV2,
+    transferV3,
+    exchangeV2,
 
     // account
     declare,
@@ -31,18 +49,42 @@ const createExecutor = ({ filter, runAsLambda }) => {
     // asset
     createAsset,
     updateAsset,
+    acquireAssetV2,
+    acquireAssetV3,
+    mintAsset,
+
+    // factory
+    createFactory,
+
+    // token
+    createToken,
+    depositTokenV2,
+    withdrawTokenV2,
 
-    // misc
-    poke,
+    // governance
+    stake,
+    revokeStake,
+    claimStake,
+
+    // rollup
+    createRollup,
+    updateRollup,
+    joinRollup,
+    leaveRollup,
+    pauseRollup,
+    resumeRollup,
+    createRollupBlock,
+    claimBlockReward,
+    migrateRollupContract,
+    migrateRollupToken,
   };
 
   const execute = executor({ filter, runAsLambda });
 
-  return Object.assign(events, {
+  return {
     ...protocols,
 
     execute: (context, done) => {
-      Object.defineProperty(context, 'emit', { value: emit });
       Object.defineProperty(context, 'states', { value: states });
 
       if (typeof done === 'function') {
@@ -53,7 +95,7 @@ const createExecutor = ({ filter, runAsLambda }) => {
 
       return execute(context, protocols);
     },
-  });
+  };
 };
 
 // default in-memory tx-hash-filter

package/lib/protocols/account/declare.js

@@ -1,28 +1,28 @@
-const isEmpty = require('empty-value');
+const Error = require('@ocap/util/lib/error');
+const Joi = require('@arcblock/validator');
 const { Runner, pipes } = require('@ocap/tx-pipeline');
 const { account } = require('@ocap/state');
 const { toBase58 } = require('@ocap/util');
 
-// eslint-disable-next-line global-require
-const debug = require('debug')(`${require('../../../package.json').name}:declare`);
-
 const runner = new Runner();
 
 runner.use(pipes.VerifyMultiSig(0));
 
-// Verify itx
-runner.use(
-  pipes.VerifyInfo([
-    {
-      error: 'INSUFFICIENT_DATA',
-      fn: ({ itx }) => !isEmpty(itx.moniker),
-    },
-    {
-      error: 'INVALID_MONIKER',
-      fn: ({ itx }) => /^[a-zA-Z0-9][-a-zA-Z0-9_]{2,40}$/.test(itx.moniker),
-    },
-  ])
-);
+// verify itx
+const schema = Joi.object({
+  issuer: Joi.DID().optional().allow(''),
+  moniker: Joi.string()
+    .regex(/^[a-zA-Z0-9][-a-zA-Z0-9_]{2,40}$/)
+    .required(),
+  data: Joi.any().optional(),
+}).options({ stripUnknown: true, noDefaults: false });
+runner.use(({ itx }, next) => {
+  const { error } = schema.validate(itx);
+  if (error) {
+    return next(new Error('INVALID_TX', `Invalid itx: ${error.message}`));
+  }
+  return next();
+});
 
 // Ensure sender does not exist
 runner.use(pipes.ExtractState({ from: 'tx.from', to: 'senderState' }));
@@ -33,18 +33,24 @@ runner.use(pipes.VerifyAccountMigration({ senderKey: 'senderState' }));
 runner.use(pipes.ExtractState({ from: 'itx.issuer', to: 'issuerState', status: 'INVALID_TX' }));
 
 // Create account state
-runner.use(async (context, next) => {
-  const { tx, itx, statedb } = context;
-
-  const attrs = { address: tx.from, pk: toBase58(tx.pk), ...itx };
-  const state = account.create(attrs, context);
-  context.senderState = state;
-
-  debug('attrs', attrs);
-
-  await statedb.account.create(tx.from, state, context);
-
-  next();
-});
+runner.use(
+  async (context, next) => {
+    const { tx, itx, statedb } = context;
+    const tokens = { [context.config.token.address]: '0' };
+
+    const [senderState] = await Promise.all([
+      statedb.account.create(
+        tx.from,
+        account.create({ address: tx.from, pk: toBase58(tx.pk), nonce: tx.nonce, tokens, ...itx }, context),
+        context
+      ),
+    ]);
+
+    context.senderState = senderState;
+
+    next();
+  },
+  { persistError: true }
+);
 
 module.exports = runner;

package/lib/protocols/account/delegate.js

@@ -1,5 +1,7 @@
+/* eslint-disable max-len */
 const get = require('lodash/get');
-const isEmpty = require('empty-value');
+const Joi = require('@arcblock/validator');
+const Error = require('@ocap/util/lib/error');
 const getListField = require('@ocap/util/lib/get-list-field');
 const { delegation, account } = require('@ocap/state');
 const { Runner, pipes } = require('@ocap/tx-pipeline');
@@ -12,6 +14,27 @@ const runner = new Runner();
 
 runner.use(pipes.VerifyMultiSig(0));
 
+// verify itx
+const schema = Joi.object({
+  address: Joi.DID().role('ROLE_DELEGATION').required(),
+  to: Joi.DID().required(),
+  opsList: Joi.array()
+    .items(
+      Joi.object({
+        typeUrl: Joi.string().required(),
+      })
+    )
+    .min(1)
+    .required(),
+  data: Joi.any().optional(),
+}).options({ stripUnknown: true, noDefaults: false });
+runner.use(({ itx }, next) => {
+  const { error } = schema.validate(itx);
+  if (error) {
+    return next(new Error('INVALID_TX', `Invalid itx: ${error.message}`));
+  }
+  return next();
+});
 runner.use(
   pipes.VerifyInfo([
     {
@@ -21,11 +44,6 @@ runner.use(
         return true;
       },
     },
-    {
-      error: 'INSUFFICIENT_DATA',
-      message: 'itx.address, itx.to and itx.ops should not be empty',
-      fn: ({ itx, ops }) => !isEmpty(itx.address) && !isEmpty(itx.to) && ops.length > 0,
-    },
     {
       error: 'INVALID_TX',
       message: 'Delegation address does not match',
@@ -44,43 +62,63 @@ runner.use(
 );
 
 // Ensure sender/receiver exist
-runner.use(pipes.ExtractState({ from: 'tx.from', to: 'senderState', status: 'INVALID_SENDER_STATE' }));
+runner.use(pipes.ExtractState({ from: 'tx.from', to: 'senderState', status: 'OK', table: 'account' }));
 runner.use(pipes.VerifyAccountMigration({ senderKey: 'senderState' }));
-runner.use(pipes.ExtractState({ from: 'itx.to', to: 'receiverState', status: 'INVALID_RECEIVER_STATE' }));
-
-// Create account state, and update old accounts
-runner.use(async (context, next) => {
-  const { tx, itx, ops, statedb, senderState } = context;
-
-  const opsObj = ops.reduce((acc, x) => {
-    acc[x.typeUrl] = {
-      balance: 0,
-      numTxs: 0,
-      rule: true, // TODO: support join x.rules to an expression
-    };
-    return acc;
-  }, {});
-
-  const exist = await statedb.delegation.get(itx.address, context);
-  let state = null;
-  if (exist) {
-    state = delegation.update(exist, { ...itx, ops: opsObj }, context);
-    debug('update', { from: tx.from, to: itx.to, state });
-    await statedb.delegation.update(itx.address, state, context);
-  } else {
-    state = delegation.create({ ...itx, ops: opsObj }, context);
-    debug('create', { from: tx.from, to: itx.to, state });
-    await statedb.delegation.create(itx.address, state, context);
-  }
+runner.use(pipes.ExtractState({ from: 'itx.to', to: 'receiverState', status: 'OK', table: 'account' }));
 
-  const newSenderState = account.update(senderState, { nonce: tx.nonce }, context);
-  await statedb.account.update(senderState.address, newSenderState, context);
+// Extract delegation
+runner.use(pipes.ExtractState({ from: 'itx.address', to: 'delegationState', table: 'delegation', status: 'OK' }));
 
-  // Update context
-  context.delegationState = state;
-  context.senderState = newSenderState;
+// Create delegation state
+runner.use(
+  async (context, next) => {
+    const { tx, itx, ops, statedb, senderState, receiverState, delegationState } = context;
 
-  return next();
-});
+    const opsObj = ops.reduce(
+      (acc, x) => {
+        acc[x.typeUrl] = {
+          balance: 0,
+          numTxs: 0,
+          // TODO: 可以考虑结合现有的 DSL 去实现
+          rule: true,
+        };
+        return acc;
+      },
+      delegationState ? delegationState.ops : {}
+    );
+
+    const sender = senderState ? senderState.address : tx.from;
+    const receiver = receiverState ? receiverState.address : itx.to;
+
+    const [newSenderState, newReceiverState, newDelegationState] = await Promise.all([
+      // update sender
+      statedb.account.updateOrCreate(
+        senderState,
+        account.updateOrCreate(senderState, { address: sender, nonce: tx.nonce, pk: tx.pk }, context),
+        context
+      ),
+
+      // update receiver
+      receiverState
+        ? Promise.resolve(receiverState)
+        : statedb.account.create(receiver, account.create({ address: receiver }, context), context),
+
+      // update delegation
+      delegationState
+        ? statedb.delegation.update(itx.address, delegation.update(delegationState, { ...itx, ops: opsObj }, context), context) // prettier-ignore
+        : statedb.delegation.create(itx.address, delegation.create({ ...itx, ops: opsObj }, context), context),
+    ]);
+
+    debug(delegationState ? 'update' : 'create', newDelegationState);
+
+    // Update context
+    context.senderState = newSenderState;
+    context.receiverState = newReceiverState;
+    context.delegationState = newDelegationState;
+
+    return next();
+  },
+  { persistError: true }
+);
 
 module.exports = runner;

package/lib/protocols/account/migrate.js

@@ -1,5 +1,7 @@
-const isEmpty = require('empty-value');
-const { Runner, Error, pipes } = require('@ocap/tx-pipeline');
+const Error = require('@ocap/util/lib/error');
+const Joi = require('@arcblock/validator');
+const getRelatedAddresses = require('@ocap/util/lib/get-related-addr');
+const { Runner, pipes } = require('@ocap/tx-pipeline');
 const { fromPublicKey, toTypeInfo } = require('@arcblock/did');
 const { account } = require('@ocap/state');
 
@@ -10,13 +12,21 @@ const runner = new Runner();
 
 runner.use(pipes.VerifyMultiSig(0));
 
-// Verify itx
+// verify itx
+const schema = Joi.object({
+  address: Joi.DID().required(),
+  pk: Joi.any().required(),
+  data: Joi.any().optional(),
+}).options({ stripUnknown: true, noDefaults: false });
+runner.use(({ itx }, next) => {
+  const { error } = schema.validate(itx);
+  if (error) {
+    return next(new Error('INVALID_TX', `Invalid itx: ${error.message}`));
+  }
+  return next();
+});
 runner.use(
   pipes.VerifyInfo([
-    {
-      error: 'INSUFFICIENT_DATA',
-      fn: ({ itx }) => !isEmpty(itx.pk) && !isEmpty(itx.address),
-    },
     {
       error: 'INVALID_RECEIVER_STATE',
       message: 'Receiver pk and address does not match',
@@ -26,57 +36,63 @@ runner.use(
 );
 
 // Ensure sender exist
-runner.use(pipes.ExtractState({ from: 'tx.from', to: 'senderState', status: 'INVALID_SENDER_STATE' }));
+runner.use(pipes.ExtractState({ from: 'tx.from', to: 'senderState', status: 'INVALID_SENDER_STATE', table: 'account' })); // prettier-ignore
 runner.use(pipes.VerifyAccountMigration({ senderKey: 'senderState' }));
 
 // Create account state, and update old accounts
-runner.use(async (context, next) => {
-  const { tx, itx, statedb } = context;
+runner.use(
+  async (context, next) => {
+    const { tx, itx, statedb } = context;
 
-  const sender = context.senderState;
-  const receiver = await statedb.account.get(itx.address, context);
+    const sender = context.senderState;
+    const receiver = await statedb.account.get(itx.address, context);
 
-  // Ensure receiver does not exist
-  if (receiver) {
-    return next(new Error('INVALID_SENDER_STATE', 'Can not migrate to an existing account'));
-  }
+    // Ensure receiver does not exist
+    if (receiver) {
+      return next(new Error('INVALID_RECEIVER_STATE', 'Can not migrate to an existing account'));
+    }
 
-  // Create new account
-  const newAccount = account.create(
-    {
-      ...sender, // copy all old account data to new account
-      address: itx.address,
-      pk: itx.pk,
-      migratedFrom: [sender.address],
-    },
-    context
-  );
-  debug('new account', newAccount);
-  await statedb.account.create(itx.address, newAccount, context);
+    // Create new account
+    const newAccount = await statedb.account.create(
+      itx.address,
+      account.create(
+        {
+          ...sender, // copy all old account data to new account
+          address: itx.address,
+          pk: itx.pk,
+          migratedFrom: [sender.address],
+        },
+        context
+      ),
+      context
+    );
+    debug('new account', newAccount);
 
-  // Update old accounts
-  const addresses = account.getRelatedAddresses(sender);
-  const states = await Promise.all(
-    addresses.map(async (address) => {
-      let state = null;
-      if (address === sender.address) {
-        state = account.update(sender, { migratedTo: itx.address, nonce: tx.nonce }, context);
-      } else {
-        const old = await statedb.account.get(address, { final: false, ...context });
-        state = account.update(old, { migratedTo: itx.address }, context);
-      }
+    // Update old accounts
+    const addresses = getRelatedAddresses(sender);
+    const states = await Promise.all(
+      addresses.map(async (address) => {
+        let state = null;
+        if (address === sender.address) {
+          state = account.update(sender, { migratedTo: itx.address, nonce: tx.nonce }, context);
+        } else {
+          const old = await statedb.account.get(address, { final: false, ...context });
+          state = account.update(old, { migratedTo: itx.address }, context);
+        }
 
-      await statedb.account.update(address, state, context);
-      return state;
-    })
-  );
-  debug('old accounts', states);
+        await statedb.account.update(address, state, context);
+        return state;
+      })
+    );
+    debug('old accounts', states);
 
-  // Update context
-  context.receiverState = newAccount;
-  context.senderState = states.find((x) => x.address === sender.from);
+    // Update context
+    context.receiverState = newAccount;
+    context.senderState = states.find((x) => x.address === sender.from);
 
-  return next();
-});
+    return next();
+  },
+  { persistError: true }
+);
 
 module.exports = runner;