feat: transfer commands

[RishabhS7]

🚀 Feature: Transfer Commands

Commit: d2205e1 — feat: transfer commands
Branch: feat/transfer-commands
Author: Rishabh Singh
Date: January 12, 2026

---

📋 Overview

This PR introduces comprehensive Title Escrow transfer functionality to the TrustVC CLI, enabling users to manage transferable records (electronic Bills of Lading) directly via command-line operations.

The feature set covers holder transfers, beneficiary nominations, endorsements, and full ownership transfers, with strong validation, encryption support, gas estimation, and dry-run capabilities.

---

✨ Key Features

🔄 Title Escrow Transfer Operations

• Transfer Holder – Transfer custody of a transferable record to a new holder.
• Nominate Beneficiary – Propose a new beneficiary (owner) for a transferable record.
• Endorse Nominated Beneficiary – Accept and complete a beneficiary nomination.
• Transfer Owners – Transfer both beneficiary and holder in a single atomic transaction.

---

📁 New CLI Commands

src/commands/title-escrow/

• change-holder.ts — Transfer holder command
• nominate-change-of-owner.ts — Nominate beneficiary command
• endorse-transfer-of-owner.ts — Endorse beneficiary nomination
• endorse-change-of-owner.ts — Complete ownership transfer
• title-escrow.ts — Main title escrow command router

---

🔧 Implementation Layer

src/implementations/title-escrow/

• transferHolder.ts – Holder transfer implementation (gas estimation support)
• nominateBeneficiary.ts – Beneficiary nomination logic
• endorseNominatedBeneficiary.ts – Nomination endorsement logic
• transferOwners.ts – Complete ownership transfer logic
• helpers.ts (shared utilities) – Title escrow contract connection, validation helpers (previous holder/beneficiary, address checks), remark encryption & validation

---

🏭 Token Registry Enhancements

mint.ts

• Extracted mint logic into a dedicated implementation
• Added:
  • EIP-1559 gas fee support
  • Network-specific gas estimation
  • Dry-run mode
  • Remark encryption support

---

🛠️ Utility Improvements

• dryRun.ts – New dry-run mode for gas estimation without execution
• cli-options.ts – Reusable interactive prompts:
  • promptNetworkSelection()
  • promptWalletSelection()
  • promptRemarkAndEncryptionKey()
• wallet.ts – Improved wallet and signer initialization
• gas-station.ts – Enhanced gas fee calculations
• transaction.ts – Improved transaction output & display
• networks.ts – Updated network configurations

---

📦 Type Definitions

src/types.ts

• BaseTitleEscrowCommand
• TitleEscrowTransferHolderCommand
• TitleEscrowNominateBeneficiaryCommand
• TitleEscrowEndorseTransferOfOwnersCommand

---

✅ Test Coverage

Added 12+ new test files, covering:

🌌 Astron Network

• Astron Mainnet (6 tests)
• Astron Testnet (6 tests)

🧪 General Coverage

• Transfer success scenarios
• Gas estimation validation
• Error handling:
  • Invalid addresses
  • Missing previous holder/beneficiary
  • Remark validation (length constraints)
• Mock contract interactions

---

📊 Change Statistics

• 38 files changed
• +2,963 additions
• −279 deletions
• Net: +2,684 lines

---

🔐 Security & Validation

• Validates previous holder & beneficiary before transfer operations
• Prevents no-op transfers (same address transfers blocked)
• Remark length enforcement (max 120 characters)
• Encrypted remarks supported
• Provider validation before gas estimation

---

🌐 Supported Networks

All commands support:

• Ethereum Mainnet & Sepolia
• Polygon Mainnet & Amoy
• XDC Network & Apothem
• Stability Mainnet & Testnet
• Astron Mainnet & Testnet
• Local development networks

---

🎯 Developer Experience

• Interactive CLI prompts for all inputs
• Clear and actionable error messages
• Transaction hash + block explorer links
• Gas fee estimation before execution
• Dry-run mode for safe testing

Summary by CodeRabbit

• New Features

  • Added Title Escrow commands: change holder, endorse change/transfer of owner, and nominate beneficiary with interactive prompts.
  • Added dry-run fee report showing estimated gas costs (incl. USD and other currencies).
  • New CLI subcommands for title-escrow and token-registry.

• Improvements

  • Mint workflow converted to guided prompts; supports encrypted wallets and multiple private-key input methods.
  • Enhanced network and wallet selection prompts.

• Tests

  • Extensive new test coverage for Title Escrow flows.

• Chores

  • Added ethers v6 runtime dependency.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds Title Escrow CLI commands (change-holder, endorse-change-owner, endorse-transfer-owner, nominate-change-of-owner), helper utilities, dry-run fee analysis, type migrations (BigNumber → BigNumberish/bigint), refactors token-registry mint flow, adds ethers v6 dependency, and extensive tests for escrow flows.

Changes

Cohort / File(s)	Summary
Dependency package.json	Added runtime dependency ethers ^6.16.0
CLI Command Entrypoints src/commands/title-escrow/index.ts, src/commands/token-registry/index.ts	New yargs subcommand wiring for title-escrow and token-registry
Title Escrow Commands src/commands/title-escrow/change-holder.ts, src/commands/title-escrow/endorse-change-of-owner.ts, src/commands/title-escrow/endorse-transfer-of-owner.ts, src/commands/title-escrow/nominate-change-of-owner.ts	New CLI command modules implementing interactive prompts, validations, on-chain operations, dry-run support, gas handling, and result reporting
Token Registry Mint src/commands/token-registry/mint.ts, (removed) src/commands/token-registry/token-registry.ts	Mint flow moved from token-registry.ts (removed) into mint.ts with prompt-driven handler and helpers
Helpers for Title Escrow src/commands/helpers.ts	New helpers: connectToTitleEscrow, validators (endorse/nominate), remark encryption helper, and related utilities
Types src/types.ts	Added BaseTitleEscrowCommand, TitleEscrowTransferHolderCommand, TitleEscrowEndorseTransferOfOwnersCommand, TitleEscrowNominateBeneficiaryCommand
CLI Prompt Utilities src/utils/cli-options.ts	Added promptNetworkSelection, promptWalletSelection, promptRemarkAndEncryptionKey
Dry-Run Fee Analysis src/utils/dryRun.ts, src/utils/index.ts	New dryRunMode and FeeDataType; exported from utils
Gas & Transaction Utilities src/utils/gas-station.ts, src/utils/transaction.ts	Migrations from BigNumber→BigNumberish/bigint; updated fee calculation, formatting, and helpers
Provider & Wallet Adjustments src/utils/networks.ts, src/utils/wallet.ts	Switched to explicit Provider/InfuraProvider/JsonRpcProvider imports; wallet returns include HDNodeWallet; AWS KMS path disabled/removed
Tests — Title Escrow tests/commands/title-escrow/*.test.ts (many files)	Large new test suites covering nominate/endorse/transfer flows across networks with extensive mocks
Tests — Misc tests/commands/token-registry/mint.test.ts, tests/utils/networks.test.ts, vitest.config.ts	Updated imports, provider tests adjusted, vitest include patterns extended to src tests

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI
    participant Prompts
    participant WalletUtils as Wallet Utils
    participant Provider
    participant TitleEscrow as TitleEscrow Contract

    User->>CLI: run title-escrow command (e.g., change-holder)
    CLI->>Prompts: promptForInputs()
    Prompts-->>CLI: command payload
    CLI->>WalletUtils: getWalletOrSigner(walletOpts)
    WalletUtils->>Provider: connect signer
    Provider-->>WalletUtils: connected signer
    CLI->>Provider: getFeeData / network info
    Provider-->>CLI: fee data
    CLI->>TitleEscrow: call contract method (transfer/nominate/endorse) with gas options
    TitleEscrow->>Provider: submit transaction
    Provider-->>TitleEscrow: tx mined (receipt)
    TitleEscrow-->>CLI: receipt
    CLI->>User: display price, tx hash, etherscan link

Loading

sequenceDiagram
    participant User
    participant DryRun
    participant Provider
    participant PriceAPI as Price Feed

    User->>DryRun: dryRunMode({transaction, estimatedGas?, network})
    DryRun->>Provider: get block & fee data / estimateGas if needed
    Provider-->>DryRun: feeData / estimatedGas
    DryRun->>PriceAPI: fetch exchange rates
    PriceAPI-->>DryRun: rates
    DryRun->>User: show gas costs and fiat estimates

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰
I hopped through prompts and signed with delight,
Nominated and endorsed under moonlight,
Gas fees inspected, dry-run in sight,
Transactions confirmed — the ledger's just right! 🥕✨

---

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Free

📥 Commits

Reviewing files that changed from the base of the PR and between 380a4ad and 9329f3f.

📒 Files selected for processing (4)

• src/commands/token-registry/index.ts
• src/commands/token-registry/mint.ts
• src/commands/token-registry/token-registry.ts
• tests/commands/token-registry/mint.test.ts

💤 Files with no reviewable changes (1)

• src/commands/token-registry/token-registry.ts

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

---

Note

🎁 Summarized by CodeRabbit Free

Your organization is on the Free plan. CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please upgrade your subscription to CodeRabbit Pro by visiting https://app.coderabbit.ai/login.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[tradetrustimda]

🎉 This PR is included in version 1.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀