status-im · saledjenic · Sep 1, 2025
@@ -22,6 +22,14 @@ go get github.com/status-im/go-wallet-sdk
   - Complete RPC method coverage (eth_*, net_*, web3_*)
   - Go-ethereum ethclient compatible interface for easy migration
 
+### Token Lists Management
+- **`pkg/tokenlists`**: Comprehensive token list management with privacy-aware fetching
+  - Multi-source support (Status, Uniswap, CoinGecko, custom sources)
+  - Privacy-aware automatic refresh with ETag support
+  - Cross-chain token management and validation
+  - Extensible parser system for custom token list formats
+  - Thread-safe concurrent access with proper synchronization
+
 ### Common Utilities
 - **`pkg/common`**: Shared utilities and constants used across the SDK
 
@@ -56,6 +64,7 @@ go-wallet-sdk/
 ├── pkg/                    # Core SDK packages
 │   ├── balance/           # Balance-related functionality
 │   ├── ethclient/         # Ethereum client with full RPC support
+│   ├── tokenlists/        # Token list management and fetching
 │   └── common/            # Shared utilities
 ├── examples/              # Usage examples
 └── README.md             # This file
@@ -65,6 +74,7 @@ go-wallet-sdk/
 
 - [Balance Fetcher](pkg/balance/fetcher/README.md) - Balance fetching functionality
 - [Ethereum Client](pkg/ethclient/README.md) - Complete Ethereum RPC client
+- [Token Lists](pkg/tokenlists/README.md) - Token list management and fetching
 - [Web Example](examples/balance-fetcher-web/README.md) - Complete web application
 
 ## Contributing

@@ -0,0 +1,85 @@
+# Token Lists Usage Example
+
+This example demonstrates how to use the `tokenlists` package from the go-wallet-sdk to manage and query cryptocurrency token lists.
+
+## Features Demonstrated
+
+1. **Basic Setup**: Creating and configuring a TokensList service with default settings
+2. **Token Queries**: Various methods to query tokens from the lists
+3. **Chain-specific Queries**: Getting tokens for specific blockchain networks
+4. **Address Lookups**: Finding specific tokens by their contract addresses
+5. **Token List Management**: Working with different token lists and their metadata
+6. **Utility Functions**: Using token key generation and parsing utilities
+7. **Refresh Operations**: Manual refresh of token lists from remote sources
+8. **Event Notifications**: Handling update notifications when token lists change
+
+## What the TokensList Package Does
+
+The `tokenlists` package provides a comprehensive solution for managing cryptocurrency token metadata across multiple blockchain networks:
+
+The example works with a minimal configuration for demonstration purposes, a real configuration will provide more tokens/token lists.
+
+## Key Components
+
+### Token Structure
+```go
+type Token struct {
+    CrossChainID string             // Unique identifier across chains
+    ChainID      uint64             // Blockchain network ID
+    Address      common.Address     // Contract address
+    Decimals     uint               // Token decimal places
+    Name         string             // Full token name
+    Symbol       string             // Token symbol (e.g., "ETH", "USDT")
+    LogoURI      string             // URL to token logo
+    CustomToken  bool               // Whether it's a user-added token
+}
+```
+
+### TokensList Interface
+```go
+type TokensList interface {
+    Start(ctx context.Context, notifyCh chan struct{}) error
+    Stop() error
+
+    UniqueTokens() []*Token
+    GetTokenByChainAddress(chainID uint64, addr common.Address) (*Token, bool)
+    GetTokensByChain(chainID uint64) []*Token
+
+    TokenLists() []*TokenList
+    TokenList(id string) (*TokenList, bool)
+
+    RefreshNow(ctx context.Context) error
+    LastRefreshTime() (time.Time, error)
+}
+```
+
+## Running the Example
+
+```bash
+cd examples/tokenlists-usage
+go run main.go
+```
+
+## Output Example
+
+The example will output information about:
+
+- Total number of tokens across all supported chains
+- Sample tokens with their metadata (name, symbol, address, etc.)
+- Chain-specific token counts (Ethereum, Optimism, Arbitrum, etc.)
+- Token lookup by specific contract address
+- Available token lists and their sources
+- Native tokens for each supported network
+- Token key generation and parsing utilities
+- Last refresh timestamp and manual refresh operations
+
+## Configuration Options
+
+The TokensList can be configured with:
+
+- **Supported Chains**: Which blockchain networks to include
+- **Token List Sources**: Remote URLs for fetching token lists
+- **Refresh Intervals**: How often to check for updates
+- **Privacy Settings**: Whether to fetch data from remote sources
+- **Custom Storage**: Implement custom storage for caching token data
+- **Logging**: Custom logger for debugging and monitoring
@@ -0,0 +1,21 @@
+module github.com/status-im/go-wallet-sdk/examples/tokenlists-usage
+
+go 1.23.0
+
+require (
+	github.com/ethereum/go-ethereum v1.16.3
+	github.com/status-im/go-wallet-sdk v0.0.0
+	go.uber.org/zap v1.27.0
+)
+
+require (
+	github.com/holiman/uint256 v1.3.2 // indirect
+	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
+	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
+	github.com/xeipuuv/gojsonschema v1.2.0 // indirect
+	go.uber.org/multierr v1.10.0 // indirect
+	golang.org/x/crypto v0.36.0 // indirect
+	golang.org/x/sys v0.31.0 // indirect
+)
+
+replace github.com/status-im/go-wallet-sdk => ../../
@@ -0,0 +1,31 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/ethereum/go-ethereum v1.16.3 h1:nDoBSrmsrPbrDIVLTkDQCy1U9KdHN+F2PzvMbDoS42Q=
+github.com/ethereum/go-ethereum v1.16.3/go.mod h1:Lrsc6bt9Gm9RyvhfFK53vboCia8kpF9nv+2Ukntnl+8=
+github.com/holiman/uint256 v1.3.2 h1:a9EgMPSC1AAaj1SZL5zIQD3WbwTuHrMGOerLjGmM/TA=
+github.com/holiman/uint256 v1.3.2/go.mod h1:EOMSn4q6Nyt9P6efbI3bueV4e1b3dGlUCXeiRV4ng7E=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f h1:J9EGpcZtP0E/raorCMxlFGSTBrsSlaDGf3jU/qvAE2c=
+github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=
+github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415/go.mod h1:GwrjFmJcFw6At/Gs6z4yjiIwzuJ1/+UwLxMQDVQXShQ=
+github.com/xeipuuv/gojsonschema v1.2.0 h1:LhYJRs+L4fBtjZUfuSZIKGeVu0QRy8e5Xi7D17UxZ74=
+github.com/xeipuuv/gojsonschema v1.2.0/go.mod h1:anYRn/JVcOK2ZgGU+IjEV4nwlhoK5sQluxsYJ78Id3Y=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.10.0 h1:S0h4aNzvfcFsC3dRF1jLoaov7oRaKqRGC/pUEJ2yvPQ=
+go.uber.org/multierr v1.10.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.27.0 h1:aJMhYGrd5QSmlpLMr2MftRKl7t8J8PTZPA732ud/XR8=
+go.uber.org/zap v1.27.0/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
+golang.org/x/crypto v0.36.0 h1:AnAEvhDddvBdpY+uR+MyHmuZzzNqXSe/GvuDeob5L34=
+golang.org/x/crypto v0.36.0/go.mod h1:Y4J0ReaxCR1IMaabaSMugxJES1EpwhBHhv2bDHklZvc=
+golang.org/x/sys v0.31.0 h1:ioabZlmFYtWhL+TRYpcnNlLwhyxaM9kWTDEmfnprqik=
+golang.org/x/sys v0.31.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=