tapass 0.1.0 → 0.2.0

package/src/tapd_responses/rpc_decoded_proof_as_proof.ts

@@ -0,0 +1,229 @@
+import outpointAsTransaction from './outpoint_as_transaction.js';
+import rpcAssetAsAsset from './rpc_asset_as_asset.js';
+import type {Asset} from './rpc_asset_as_asset.js';
+import type {RpcAsset} from './rpc_asset_as_asset.js';
+
+const hexOf = (n?: Buffer | null) =>
+  !n?.length ? undefined : n.toString('hex');
+const {isArray} = Array;
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const metaTypes: Record<string, string> = {
+  META_TYPE_JSON: 'json',
+  META_TYPE_OPAQUE: 'opaque',
+};
+
+export type RpcDecodedProof = {
+  alt_leaves: Buffer;
+  asset: RpcAsset | null;
+  challenge_witness: Buffer[];
+  exclusion_proofs: Buffer[];
+  genesis_reveal: {
+    genesis_base_reveal: {
+      asset_id: Buffer;
+      asset_type: string;
+      genesis_point: string;
+      meta_hash: Buffer;
+      name: string;
+      output_index: number;
+    } | null;
+  } | null;
+  group_key_reveal: {raw_group_key: Buffer; tapscript_root: Buffer} | null;
+  inclusion_proof: Buffer;
+  is_burn: boolean;
+  meta_reveal: {data: Buffer; meta_hash: Buffer; type: string} | null;
+  num_additional_inputs: number;
+  number_of_proofs: number;
+  proof_at_depth: number;
+  split_root_proof: Buffer;
+  tx_merkle_proof: Buffer;
+};
+
+export type Proof = {
+  /** Additional Inputs Count */
+  additional_inputs_count: number;
+  /** Alternative Leaves Hex */
+  alt_leaves?: string;
+  asset: Asset;
+  /** Challenge Witness Elements Hex */
+  challenge_witness: string[];
+  /** Proof Depth From the Last Proof In the File */
+  depth: number;
+  /** Exclusion Proofs Hex */
+  exclusion_proofs: string[];
+  genesis?: {
+    /** Asset Id Hex */
+    asset_id: string;
+    /** Asset Is Collectible */
+    is_collectible: boolean;
+    /** Asset Metadata Hash Hex */
+    meta_hash: string;
+    /** Asset Name */
+    name: string;
+    /** Genesis Commitment Output Index */
+    output_index: number;
+    /** Genesis Point Transaction Id Hex */
+    transaction_id: string;
+    /** Genesis Point Transaction Output Index */
+    transaction_vout: number;
+  };
+  group_key?: {
+    /** Raw Group Key Hex */
+    raw_key: string;
+    /** Group Tapscript Root Hex */
+    tapscript_root?: string;
+  };
+  /** Inclusion Proof Hex */
+  inclusion_proof: string;
+  /** Proof Is For a Burn */
+  is_burn: boolean;
+  meta?: {
+    /** Metadata Hex */
+    data: string;
+    /** Metadata Hash Hex */
+    hash: string;
+    /** Metadata Type */
+    type: string;
+  };
+  /** Proofs In the File Count */
+  proofs_count: number;
+  /** Split Root Proof Hex */
+  split_root_proof?: string;
+  /** Transaction Merkle Proof Hex */
+  transaction_merkle_proof: string;
+};
+
+/** Proof from an RPC decoded proof
+
+  {
+    alt_leaves: <Alternative Leaves Buffer Object>
+    asset: <RPC Asset Object>
+    challenge_witness: [<Challenge Witness Element Buffer Object>]
+    exclusion_proofs: [<Exclusion Proof Buffer Object>]
+    [genesis_reveal]: {
+      [genesis_base_reveal]: {
+        asset_id: <Asset Id Buffer Object>
+        asset_type: <Asset Type String>
+        genesis_point: <Genesis Outpoint String>
+        meta_hash: <Metadata Hash Buffer Object>
+        name: <Asset Name String>
+        output_index: <Genesis Commitment Output Index Number>
+      }
+    }
+    [group_key_reveal]: {
+      raw_group_key: <Raw Group Key Buffer Object>
+      tapscript_root: <Group Tapscript Root Buffer Object>
+    }
+    inclusion_proof: <Inclusion Proof Buffer Object>
+    is_burn: <Proof Is For a Burn Bool>
+    [meta_reveal]: {
+      data: <Metadata Buffer Object>
+      meta_hash: <Metadata Hash Buffer Object>
+      type: <Metadata Type String>
+    }
+    num_additional_inputs: <Additional Inputs Count Number>
+    number_of_proofs: <Proofs In the File Count Number>
+    proof_at_depth: <Proof Depth Number>
+    split_root_proof: <Split Root Proof Buffer Object>
+    tx_merkle_proof: <Transaction Merkle Proof Buffer Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    additional_inputs_count: <Additional Inputs Count Number>
+    [alt_leaves]: <Alternative Leaves Hex String>
+    asset: <Asset Object>
+    challenge_witness: [<Challenge Witness Element Hex String>]
+    depth: <Proof Depth From the Last Proof In the File Number>
+    exclusion_proofs: [<Exclusion Proof Hex String>]
+    [genesis]: {
+      asset_id: <Asset Id Hex String>
+      is_collectible: <Asset Is Collectible Bool>
+      meta_hash: <Asset Metadata Hash Hex String>
+      name: <Asset Name String>
+      output_index: <Genesis Commitment Output Index Number>
+      transaction_id: <Genesis Point Transaction Id Hex String>
+      transaction_vout: <Genesis Point Transaction Output Index Number>
+    }
+    [group_key]: {
+      raw_key: <Raw Group Key Hex String>
+      [tapscript_root]: <Group Tapscript Root Hex String>
+    }
+    inclusion_proof: <Inclusion Proof Hex String>
+    is_burn: <Proof Is For a Burn Bool>
+    [meta]: {
+      data: <Metadata Hex String>
+      hash: <Metadata Hash Hex String>
+      type: <Metadata Type String> // json, opaque, unknown
+    }
+    proofs_count: <Proofs In the File Count Number>
+    [split_root_proof]: <Split Root Proof Hex String>
+    transaction_merkle_proof: <Transaction Merkle Proof Hex String>
+  }
+*/
+export default (proof?: RpcDecodedProof | null): Proof => {
+  if (!proof) {
+    throw new Error('ExpectedRpcDecodedProofDetails');
+  }
+
+  if (!isArray(proof.challenge_witness)) {
+    throw new Error('ExpectedChallengeWitnessInRpcDecodedProof');
+  }
+
+  if (!isArray(proof.exclusion_proofs)) {
+    throw new Error('ExpectedExclusionProofsInRpcDecodedProof');
+  }
+
+  if (!isBuffer(proof.inclusion_proof)) {
+    throw new Error('ExpectedInclusionProofInRpcDecodedProof');
+  }
+
+  if (!isBuffer(proof.tx_merkle_proof)) {
+    throw new Error('ExpectedTransactionMerkleProofInRpcDecodedProof');
+  }
+
+  const genesis = proof.genesis_reveal?.genesis_base_reveal;
+  const group = proof.group_key_reveal;
+  const meta = proof.meta_reveal;
+
+  const hasGenesis = !!genesis?.asset_id?.length;
+
+  return {
+    additional_inputs_count: proof.num_additional_inputs,
+    alt_leaves: hexOf(proof.alt_leaves),
+    asset: rpcAssetAsAsset(proof.asset),
+    challenge_witness: proof.challenge_witness.map(n => n.toString('hex')),
+    depth: proof.proof_at_depth,
+    exclusion_proofs: proof.exclusion_proofs.map(n => n.toString('hex')),
+    genesis: !hasGenesis
+      ? undefined
+      : {
+          asset_id: genesis.asset_id.toString('hex'),
+          is_collectible: genesis.asset_type === 'COLLECTIBLE',
+          meta_hash: genesis.meta_hash.toString('hex'),
+          name: genesis.name,
+          output_index: genesis.output_index,
+          ...outpointAsTransaction(genesis.genesis_point),
+        },
+    group_key: !group?.raw_group_key?.length
+      ? undefined
+      : {
+          raw_key: group.raw_group_key.toString('hex'),
+          tapscript_root: hexOf(group.tapscript_root),
+        },
+    inclusion_proof: proof.inclusion_proof.toString('hex'),
+    is_burn: proof.is_burn,
+    meta: !meta?.meta_hash?.length
+      ? undefined
+      : {
+          data: meta.data.toString('hex'),
+          hash: meta.meta_hash.toString('hex'),
+          type: metaTypes[meta.type] || 'unknown',
+        },
+    proofs_count: proof.number_of_proofs,
+    split_root_proof: hexOf(proof.split_root_proof),
+    transaction_merkle_proof: proof.tx_merkle_proof.toString('hex'),
+  };
+};

package/src/tapd_responses/rpc_forward_as_asset_forward.ts

@@ -0,0 +1,164 @@
+import fixedPointAsDecimal from './fixed_point_as_decimal.js';
+import type {RpcFixedPoint} from './fixed_point_as_decimal.js';
+import type {RpcAssetSpec} from './rpc_buy_quote_as_quote.js';
+import shortChannelIdAsChannel from './short_channel_id_as_channel.js';
+
+const dateFrom = (n: string) => new Date(Number(n) * 1e3).toISOString();
+const hexOf = (n?: Buffer | null) =>
+  !n?.length ? undefined : n.toString('hex');
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+const policyTypes: Record<string, AssetForward['type']> = {
+  RFQ_POLICY_TYPE_PURCHASE: 'purchase',
+  RFQ_POLICY_TYPE_SALE: 'sale',
+};
+const zero = '0';
+
+export type RpcForwardingEvent = {
+  amt_in_msat: string;
+  amt_out_msat: string;
+  asset_amt: string;
+  asset_spec: RpcAssetSpec;
+  chan_id_in: string;
+  chan_id_out: string;
+  failed_at: string;
+  htlc_id: string;
+  opened_at: string;
+  peer: string;
+  policy_type: string;
+  rate: RpcFixedPoint | null;
+  rfq_id: Buffer;
+  settled_at: string;
+};
+
+export type AssetForward = {
+  /** Swapped Asset Units Numeric String */
+  amount: string;
+  /** Asset Id Hex */
+  asset_id?: string;
+  /** Forward Failed At ISO 8601 Date */
+  failed_at?: string;
+  /** Asset Group BIP340 Public Key Hex */
+  group_key?: string;
+  /** Incoming HTLC Index Numeric String */
+  htlc_index: string;
+  /** Incoming Standard Format Channel Id */
+  incoming_channel: string;
+  /** Received Millitokens String */
+  incoming_mtokens: string;
+  /** Forward Started At ISO 8601 Date */
+  opened_at: string;
+  /** Outgoing Standard Format Channel Id */
+  outgoing_channel: string;
+  /** Sent Millitokens String */
+  outgoing_mtokens: string;
+  /** Peer Public Key Hex */
+  peer_public_key?: string;
+  /** Rate Asset Units Per BTC Exact Decimal String */
+  rate?: string;
+  /** RFQ Session Id Hex */
+  rfq_id: string;
+  /** Forward Settled At ISO 8601 Date */
+  settled_at?: string;
+  /** Edge Node Policy Type */
+  type: 'purchase' | 'sale';
+};
+
+/** Asset forward from an RPC RFQ forwarding event
+
+  {
+    amt_in_msat: <Received Millisatoshis Numeric String>
+    amt_out_msat: <Sent Millisatoshis Numeric String>
+    asset_amt: <Swapped Asset Units Numeric String>
+    [asset_spec]: {
+      group_pub_key: <Asset Group BIP340 Public Key Buffer Object>
+      id: <Asset Id Buffer Object>
+    }
+    chan_id_in: <Incoming Short Channel Id Numeric String>
+    chan_id_out: <Outgoing Short Channel Id Numeric String>
+    failed_at: <Failed At Unix Seconds Numeric String> // 0 is not failed
+    htlc_id: <Incoming HTLC Index Numeric String>
+    opened_at: <Started At Unix Seconds Numeric String>
+    peer: <Peer Public Key Hex String>
+    policy_type: <Policy Type String>
+    [rate]: {
+      coefficient: <Scaled Integer Numeric String>
+      scale: <Decimal Places Number>
+    }
+    rfq_id: <RFQ Session Id Buffer Object>
+    settled_at: <Settled At Unix Seconds Numeric String> // 0 is not settled
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    amount: <Swapped Asset Units Numeric String>
+    [asset_id]: <Asset Id Hex String>
+    [failed_at]: <Forward Failed At ISO 8601 Date String>
+    [group_key]: <Asset Group BIP340 Public Key Hex String>
+    htlc_index: <Incoming HTLC Index Numeric String>
+    incoming_channel: <Incoming Standard Format Channel Id String>
+    incoming_mtokens: <Received Millitokens String>
+    opened_at: <Forward Started At ISO 8601 Date String>
+    outgoing_channel: <Outgoing Standard Format Channel Id String>
+    outgoing_mtokens: <Sent Millitokens String>
+    [peer_public_key]: <Peer Public Key Hex String>
+    [rate]: <Rate Asset Units Per BTC Exact Decimal String>
+    rfq_id: <RFQ Session Id Hex String>
+    [settled_at]: <Forward Settled At ISO 8601 Date String>
+    type: <Edge Node Policy Type String> // purchase, sale
+  }
+*/
+export default (forward?: RpcForwardingEvent | null): AssetForward => {
+  if (!forward) {
+    throw new Error('ExpectedRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.amt_in_msat) || !isNumeric(forward.amt_out_msat)) {
+    throw new Error('ExpectedMsatAmountsInRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.asset_amt)) {
+    throw new Error('ExpectedAssetAmountInRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.htlc_id)) {
+    throw new Error('ExpectedHtlcIdInRpcForwardingEvent');
+  }
+
+  if (!isNumeric(forward.opened_at)) {
+    throw new Error('ExpectedOpenedAtInRpcForwardingEvent');
+  }
+
+  if (!policyTypes[forward.policy_type]) {
+    throw new Error('ExpectedKnownPolicyTypeInRpcForwardingEvent');
+  }
+
+  if (!isBuffer(forward.rfq_id) || !forward.rfq_id.length) {
+    throw new Error('ExpectedRfqIdInRpcForwardingEvent');
+  }
+
+  const failedAt = forward.failed_at;
+  const settledAt = forward.settled_at;
+
+  return {
+    amount: forward.asset_amt,
+    asset_id: hexOf(forward.asset_spec?.id),
+    failed_at: !!failedAt && failedAt !== zero ? dateFrom(failedAt) : undefined,
+    group_key: hexOf(forward.asset_spec?.group_pub_key),
+    htlc_index: forward.htlc_id,
+    incoming_channel: shortChannelIdAsChannel(forward.chan_id_in),
+    incoming_mtokens: forward.amt_in_msat,
+    opened_at: dateFrom(forward.opened_at),
+    outgoing_channel: shortChannelIdAsChannel(forward.chan_id_out),
+    outgoing_mtokens: forward.amt_out_msat,
+    peer_public_key: forward.peer || undefined,
+    rate: !forward.rate ? undefined : fixedPointAsDecimal(forward.rate),
+    rfq_id: forward.rfq_id.toString('hex'),
+    settled_at:
+      !!settledAt && settledAt !== zero ? dateFrom(settledAt) : undefined,
+    type: policyTypes[forward.policy_type],
+  };
+};

package/src/tapd_responses/rpc_grouped_assets_as_group.ts

@@ -0,0 +1,117 @@
+const assetVersions = ['ASSET_VERSION_V0', 'ASSET_VERSION_V1'];
+const {isArray} = Array;
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isGroupKey = (n: string) => /^0[23][0-9a-f]{64}$/i.test(n);
+const isNumeric = (n: unknown) => typeof n === 'string' && /^\d+$/.test(n);
+
+export type RpcGroupedAssets = {
+  assets: {
+    amount: string;
+    id: Buffer;
+    lock_time: number;
+    meta_hash: Buffer;
+    relative_lock_time: number;
+    tag: string;
+    type: string;
+    version: string;
+  }[];
+};
+
+export type Group = {
+  assets: {
+    /** Asset Units Numeric String */
+    amount: string;
+    /** Asset Id Hex */
+    asset_id: string;
+    /** Asset Is Collectible */
+    is_collectible: boolean;
+    /** Lock Time */
+    lock_time?: number;
+    /** Asset Metadata Hash Hex */
+    meta_hash: string;
+    /** Asset Name */
+    name: string;
+    /** Relative Lock Time */
+    relative_lock_time?: number;
+    /** Asset Version */
+    version: number;
+  }[];
+  /** Tweaked Group Key Hex */
+  key: string;
+};
+
+/** Group from an RPC group key and its grouped assets
+
+  {
+    key: <Tweaked Group Key Hex String>
+    group: {
+      assets: [{
+        amount: <Asset Units Numeric String>
+        id: <Asset Id Buffer Object>
+        lock_time: <Lock Time Number>
+        meta_hash: <Asset Metadata Hash Buffer Object>
+        relative_lock_time: <Relative Lock Time Number>
+        tag: <Asset Name String>
+        type: <Asset Type String>
+        version: <Asset Version String>
+      }]
+    }
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    assets: [{
+      amount: <Asset Units Numeric String>
+      asset_id: <Asset Id Hex String>
+      is_collectible: <Asset Is Collectible Bool>
+      [lock_time]: <Lock Time Number>
+      meta_hash: <Asset Metadata Hash Hex String>
+      name: <Asset Name String>
+      [relative_lock_time]: <Relative Lock Time Number>
+      version: <Asset Version Number>
+    }]
+    key: <Tweaked Group Key Hex String>
+  }
+*/
+export default ({
+  group,
+  key,
+}: {
+  group?: RpcGroupedAssets | null;
+  key: string;
+}): Group => {
+  if (!isGroupKey(key)) {
+    throw new Error('ExpectedGroupKeyForRpcGroupedAssets');
+  }
+
+  if (!group || !isArray(group.assets)) {
+    throw new Error('ExpectedArrayOfAssetsInRpcGroupedAssets');
+  }
+
+  return {
+    key,
+    assets: group.assets.map(asset => {
+      if (!isNumeric(asset?.amount)) {
+        throw new Error('ExpectedAmountInRpcGroupedAsset');
+      }
+
+      if (!isBuffer(asset.id) || !isBuffer(asset.meta_hash)) {
+        throw new Error('ExpectedAssetIdAndMetaHashInRpcGroupedAsset');
+      }
+
+      return {
+        amount: asset.amount,
+        asset_id: asset.id.toString('hex'),
+        is_collectible: asset.type === 'COLLECTIBLE',
+        lock_time: asset.lock_time || undefined,
+        meta_hash: asset.meta_hash.toString('hex'),
+        name: asset.tag,
+        relative_lock_time: asset.relative_lock_time || undefined,
+        version: assetVersions.indexOf(asset.version),
+      };
+    }),
+  };
+};

package/src/tapd_responses/rpc_managed_utxo_as_utxo.ts

@@ -0,0 +1,105 @@
+import outpointAsTransaction from './outpoint_as_transaction.js';
+import rpcAssetAsAsset from './rpc_asset_as_asset.js';
+import type {Asset} from './rpc_asset_as_asset.js';
+import type {RpcAsset} from './rpc_asset_as_asset.js';
+
+const dateFrom = (n: string) => new Date(Number(n) * 1e3).toISOString();
+const {isArray} = Array;
+const isBuffer = (n: unknown): n is Buffer => Buffer.isBuffer(n);
+const isInteger = (n: unknown) => typeof n === 'string' && /^-?\d+$/.test(n);
+
+export type RpcManagedUtxo = {
+  amt_sat: string;
+  assets: RpcAsset[];
+  internal_key: Buffer;
+  lease_expiry_unix: string;
+  lease_owner: Buffer;
+  merkle_root: Buffer;
+  out_point: string;
+  taproot_asset_root: Buffer;
+};
+
+export type Utxo = {
+  assets: Asset[];
+  /** Internal Key Hex */
+  internal_key: string;
+  /** Lease Expires At ISO 8601 Date */
+  lease_expires_at?: string;
+  /** Lease Owner Id Hex */
+  lease_owner?: string;
+  /** Taproot Merkle Root Hex */
+  merkle_root: string;
+  /** Taproot Asset Root Commitment Hash Hex */
+  taproot_asset_root: string;
+  /** Output Value Tokens */
+  tokens: number;
+  /** Transaction Id Hex */
+  transaction_id: string;
+  /** Transaction Output Index */
+  transaction_vout: number;
+};
+
+/** UTXO from an RPC managed UTXO
+
+  {
+    amt_sat: <Output Value Satoshis Numeric String>
+    assets: [<RPC Asset Object>]
+    internal_key: <Internal Key Buffer Object>
+    lease_expiry_unix: <Lease Expires At Unix Seconds Numeric String>
+    lease_owner: <Lease Owner Id Buffer Object>
+    merkle_root: <Taproot Merkle Root Buffer Object>
+    out_point: <Outpoint String>
+    taproot_asset_root: <Taproot Asset Root Commitment Hash Buffer Object>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    assets: [<Asset Object>]
+    internal_key: <Internal Key Hex String>
+    [lease_expires_at]: <Lease Expires At ISO 8601 Date String>
+    [lease_owner]: <Lease Owner Id Hex String>
+    merkle_root: <Taproot Merkle Root Hex String>
+    taproot_asset_root: <Taproot Asset Root Commitment Hash Hex String>
+    tokens: <Output Value Tokens Number>
+    transaction_id: <Transaction Id Hex String>
+    transaction_vout: <Transaction Output Index Number>
+  }
+*/
+export default (utxo?: RpcManagedUtxo | null): Utxo => {
+  if (!utxo) {
+    throw new Error('ExpectedRpcManagedUtxoDetails');
+  }
+
+  if (!isInteger(utxo.amt_sat)) {
+    throw new Error('ExpectedOutputValueInRpcManagedUtxo');
+  }
+
+  if (!isArray(utxo.assets)) {
+    throw new Error('ExpectedArrayOfAssetsInRpcManagedUtxo');
+  }
+
+  if (!isBuffer(utxo.internal_key) || !isBuffer(utxo.merkle_root)) {
+    throw new Error('ExpectedKeysInRpcManagedUtxo');
+  }
+
+  if (!isBuffer(utxo.taproot_asset_root)) {
+    throw new Error('ExpectedTaprootAssetRootInRpcManagedUtxo');
+  }
+
+  // tapd sends the zero time as the expiry when there is no lease
+  const hasLease = !!utxo.lease_owner?.length;
+
+  return {
+    assets: utxo.assets.map(rpcAssetAsAsset),
+    internal_key: utxo.internal_key.toString('hex'),
+    lease_expires_at: hasLease ? dateFrom(utxo.lease_expiry_unix) : undefined,
+    lease_owner: hasLease ? utxo.lease_owner.toString('hex') : undefined,
+    merkle_root: utxo.merkle_root.toString('hex'),
+    taproot_asset_root: utxo.taproot_asset_root.toString('hex'),
+    tokens: Number(utxo.amt_sat),
+    ...outpointAsTransaction(utxo.out_point),
+  };
+};

package/src/tapd_responses/rpc_receive_event_as_receive_update.ts

@@ -0,0 +1,84 @@
+import outpointAsTransaction from './outpoint_as_transaction.js';
+import receiveStatuses from './receive_statuses.js';
+import rpcAddrAsAddress from './rpc_addr_as_address.js';
+import type {Address} from './rpc_addr_as_address.js';
+import type {RpcAddr} from './rpc_addr_as_address.js';
+
+const isInteger = (n: unknown) => typeof n === 'string' && /^-?\d+$/.test(n);
+const microsPerMilli = 1e3;
+
+export type RpcReceiveEvent = {
+  address: RpcAddr | null;
+  confirmation_height: number;
+  error: string;
+  outpoint: string;
+  status: string;
+  timestamp: string;
+};
+
+export type ReceiveUpdate = {
+  address: Address;
+  /** Confirmation Block Height */
+  confirmation_height?: number;
+  /** Receive Error */
+  error?: string;
+  /** Receive Status */
+  status: string;
+  /** Anchor Transaction Id Hex */
+  transaction_id?: string;
+  /** Anchor Transaction Output Index */
+  transaction_vout?: number;
+  /** Updated At ISO 8601 Date */
+  updated_at: string;
+};
+
+/** Receive update from an RPC receive event
+
+  {
+    address: <RPC Address Object>
+    confirmation_height: <Confirmation Block Height Number>
+    error: <Receive Error String>
+    outpoint: <Anchor Outpoint String>
+    status: <Address Event Status String>
+    timestamp: <Event Unix Microseconds Numeric String>
+  }
+
+  @throws
+  <Error>
+
+  @returns
+  {
+    address: <Address Object>
+    [confirmation_height]: <Confirmation Block Height Number>
+    [error]: <Receive Error String>
+    status: <Receive Status String>
+    [transaction_id]: <Anchor Transaction Id Hex String>
+    [transaction_vout]: <Anchor Transaction Output Index Number>
+    updated_at: <Updated At ISO 8601 Date String>
+  }
+*/
+export default (event?: RpcReceiveEvent | null): ReceiveUpdate => {
+  if (!event) {
+    throw new Error('ExpectedRpcReceiveEventDetails');
+  }
+
+  if (!receiveStatuses[event.status]) {
+    throw new Error('ExpectedKnownStatusInRpcReceiveEvent');
+  }
+
+  if (!isInteger(event.timestamp)) {
+    throw new Error('ExpectedTimestampInRpcReceiveEvent');
+  }
+
+  // tapd sends the time of the event in microseconds
+  const millis = Number(event.timestamp) / microsPerMilli;
+
+  return {
+    address: rpcAddrAsAddress(event.address),
+    confirmation_height: event.confirmation_height || undefined,
+    error: event.error || undefined,
+    status: receiveStatuses[event.status],
+    updated_at: new Date(millis).toISOString(),
+    ...(!event.outpoint ? {} : outpointAsTransaction(event.outpoint)),
+  };
+};