Skip to content

Conversation

@fatsheep2
Copy link
Contributor

Description

This PR adds support for OKLink blockchain explorer provider, enabling users to convert token transfer records from OKLink (Ethereum ERC20 and TRON TRC20) to Beancount format.

Key Features:

  • Support for Ethereum (ERC20) and TRON (TRC20) token transfers
  • Multi-address configuration support
  • Flexible rule-based matching system
  • Automatic direction detection (send/receive)
  • Handles unverified tokens (address format in token symbol field)

Improvements:

  • Enhanced documentation with comprehensive examples
  • Anonymized all sensitive data in example files (addresses, transaction hashes)
  • Improved handling of unverified tokens (no longer skipped, allows user customization via rules)
  • English warning logs with contract addresses for easier rule configuration

Motivation and Context

OKLink is a popular blockchain explorer that supports multiple chains and doesn't require account registration. Many users need to track their cryptocurrency token transfers from OKLink exports. This provider enables seamless conversion of OKLink CSV exports to Beancount format with flexible configuration options.

Key Design Decisions:

  1. Multi-address support: Users can configure multiple addresses in a single config file, useful for managing multiple wallets
  2. Unverified token handling: Instead of skipping unverified tokens (where token symbol is an address), we now process them and allow users to customize via rules, giving users full control
  3. Address-based configuration: Using addresses as keys in configuration allows automatic direction detection and per-address rule customization

Dependencies

No new dependencies required. Uses existing Go standard library and project dependencies.

Type of change

  • New feature (non-breaking change which adds functionality)
  • This change requires a documentation update

How has this been tested?

Test A: Ethereum (ERC20) Token Transfer

  1. Exported token transfer CSV from OKLink for an Ethereum address
  2. Created configuration file with address and rules
  3. Ran deg translate -p oklink -c config.yaml -o output.bean input.csv
  4. Verified Beancount output contains correct transactions with proper account mapping
  5. Verified direction detection (send/receive) works correctly
  6. Tested with USDT, USDC, and other ERC20 tokens

Test B: TRON (TRC20) Token Transfer

  1. Exported token transfer CSV from OKLink for a TRON address
  2. Created configuration file with TRON address and rules
  3. Ran conversion command
  4. Verified output correctly handles TRON address format (T-prefixed)
  5. Verified TRC20 token transfers are correctly parsed

Test C: Multi-address Configuration

  1. Created config with both Ethereum and TRON addresses
  2. Processed CSV files containing transactions from both addresses
  3. Verified each address's rules are applied correctly
  4. Verified transactions are matched to correct address configuration

Test D: Unverified Token Handling

  1. Processed CSV containing unverified tokens (token symbol is address format)
  2. Verified warning logs are generated with contract addresses
  3. Created rules using contract address to handle these tokens
  4. Verified transactions are processed correctly with custom rules

Test E: Rule Matching

  1. Tested various rule matching scenarios:
    • Token symbol matching
    • Contract address matching
    • Peer address matching
    • Amount range matching
    • Direction-based matching
  2. Verified rule priority and matching logic

Test Configuration:

  • Go version: 1.21+
  • Tested with real OKLink CSV exports (anonymized for examples)
  • Configuration files tested with various rule combinations

Is this change properly documented?

  • Documentation updated in docs/providers/crypto/oklink.md
  • Example configuration file provided in example/oklink/config.yaml
  • Example CSV file provided (anonymized) in example/oklink/example-oklink-token-transfer.csv
  • Example output file provided in example/oklink/example-oklink-output.beancount
  • Comprehensive FAQ section added
  • Multiple configuration examples provided
  • All sensitive data anonymized (addresses, transaction hashes)

Documentation includes:

  • Quick start guide
  • Configuration reference
  • Multiple practical examples
  • FAQ section addressing common questions
  • Clear explanation of supported chains (Ethereum and TRON only)
  • Instructions for handling unverified tokens

- Add OKLink provider supporting ERC20 and TRC20 token transfers
- Support multi-address configuration with flexible rule-based matching
- Add automatic direction detection (send/receive)
- Handle unverified tokens with address format in token symbol field
- Add comprehensive documentation and examples
- Add crypto order type support in beancount compiler
- Update README with OKLink provider link
- Change build command to use the correct source directory for wasm files.
- Enhance error handling for locating wasm_exec.js, checking both lib and misc directories in GOROOT.
@fatsheep2 fatsheep2 requested review from a team, Triple-Z and gaocegege as code owners November 12, 2025 14:07
@fatsheep2
Copy link
Contributor Author

@Triple-Z For #190, the latest master branch was used as the base, most unrelated history was removed, and only changes related to oklink are included. Please review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant