Tron Wallet Snap

A MetaMask Snap for managing Tron network accounts. The snap now supports the complete account lifecycle and core keyring capabilities such as TRX transfers, transaction signing / broadcasting, and message signing.

📚 文档

• API 文档 - 完整的 API 参考和使用指南
• MetaMask Snaps 文档
• Keyring API 规范

Features

• Create Tron accounts (mainnet and Shasta testnet)
• List / get / delete Tron accounts and filter by chain
• Discover accounts derived from a mnemonic
• List assets and fetch account balances via MetaMask Keyring API
• Query on-chain transaction history (via TronGrid)
• Sign messages using the account private key
• Build + sign + send TRX transfers via keyring_submitRequest
• Sign raw transactions and broadcast signed payloads

RPC Methods

In addition to the Keyring API, the snap exposes convenience RPC helpers (invoked via wallet_invokeSnap):

• tron_sendTransfer – build/sign/broadcast a TRX transfer
• tron_signMessage – sign arbitrary strings with the selected account
• tron_signTransaction – sign a raw transaction hex blob
• tron_broadcastTransaction – broadcast a signed payload to TronGrid

See the /tron page in the site package for a working UI that calls these RPC methods end-to-end.

Development

# Install dependencies
yarn install

# Build the snap
yarn build

# Start development server
yarn start

# Run tests
yarn test

# Run tests in watch mode
yarn test:watch

Usage

This snap implements the Keyring API and can be used through MetaMask's keyring interface.

Quick Start

const snapId = 'npm:tron-wallet-snap';

// 1. Install the snap
await window.ethereum.request({
  method: 'wallet_requestSnaps',
  params: { [snapId]: {} },
});

// 2. Create a Tron account
const account = await window.ethereum.request({
  method: 'wallet_invokeKeyring',
  params: {
    snapId,
    request: {
      method: 'keyring_createAccount',
      params: {
        options: {
          scope: 'tron:mainnet',
          accountNameSuggestion: 'My Tron Account',
        },
      },
    },
  },
});

console.log('Account address:', account.address);

Creating an Account

To create a Tron account, use the keyring_createAccount method with the following options:

{
  scope: 'tron:mainnet', // or 'tron:shasta'
  entropySource: 'm', // optional, defaults to 'm'
  index: 0, // optional, auto-increments if not provided
  derivationPath: "m/44'/195'/0'/0/0", // optional, overrides index
  accountNameSuggestion: 'My Tron Account' // optional
}

For detailed API documentation, see API.md.

Architecture

The snap follows a clean architecture pattern:

• Entities: Core domain models (TronAccount, etc.)
• Infrastructure: Adapters for external services (SnapClient, Logger)
• Store: Data persistence layer (TronAccountRepository)
• Use Cases: Business logic (AccountUseCases)
• Handlers: API handlers (KeyringHandler)

Manual Verification (QA Checklist)

1. Environment

   • cd packages/tron-snap && yarn start to watch/rebuild the snap.
   • cd packages/site && yarn start to run the test dapp at http://localhost:8000/tron.
   • Install MetaMask Flask, connect to the site, and approve the snap.

2. Account lifecycle

   • Use the /tron page to create both mainnet & Shasta accounts.
   • Run keyring_listAccounts / keyring_getAccount / keyring_deleteAccount via the UI buttons.

3. Balance & history

   • Select an account → “List Assets” → “Get Balances” → “List Transactions”.
   • Cross-check returned balances with TronScan if needed.

4. Submit request capabilities

   • Message signing: click “Sign Message” in the test page, confirm signature appears in console.
   • Send transfer: fill recipient address & amount, invoke “Send Transfer” (snap builds + signs + broadcasts). Verify returned txid on TronScan (testnet if using Shasta scope).
   • Sign transaction: provide transaction hex, ensure snap returns signed payload.
   • Broadcast transaction: paste signed payload, ensure txid is returned.

5. Error scenarios

   • Try invoking submitRequest with an unknown account id to confirm snap surfaces Account not found.
   • Disconnect network or use invalid TronGrid endpoint to verify ExternalServiceError logging.

Notes

• Tron addresses are generated using the BIP44 derivation path m/44'/195'/0'/0/index.
• Uses Keccak-256 for address generation (standard for Tron) and Base58Check encoding.
• The snap communicates with TronGrid for balances, transactions, and latest block metadata.

Testing

The project includes comprehensive test coverage:

• Unit Tests: Test individual components and functions
  • KeyringHandler.test.ts - Tests for the Keyring API handler
  • AccountUseCases.test.ts - Tests for account business logic
  • TronAccountRepository.test.ts - Tests for account persistence
  • mappings.test.ts - Tests for data mapping functions

Run tests with:

yarn test

Site Integration

A test page is available at /tron in the site package to interact with the Tron snap:

1. Start the Tron snap: cd packages/tron-snap && yarn start
2. Start the site: cd packages/site && yarn start
3. Navigate to http://localhost:8000/tron in your browser
4. Connect MetaMask Flask and install the Tron snap
5. Create and manage Tron accounts