From 3ba359bd4bc2cd0ce18d6b7d6c8d68f63167434b Mon Sep 17 00:00:00 2001
From: melonges <melonges@duck.com>
Date: Tue, 7 Apr 2026 16:30:14 +0300
Subject: [PATCH] Enhance README with usage and API documentation

Updated the README to reflect new usage examples and API details, including additional exported methods and address constructors.
---
 packages/filecoin-address/README.md | 91 +++++++++++++++++++++++------
 1 file changed, 73 insertions(+), 18 deletions(-)

diff --git a/packages/filecoin-address/README.md b/packages/filecoin-address/README.md
index 0d16491f..79cbb8f8 100644
--- a/packages/filecoin-address/README.md
+++ b/packages/filecoin-address/README.md
@@ -9,30 +9,85 @@ This is a JS implementation of the Filecoin address type, inspired by [go-addres
 ## Usage
 
 ```js
-const { newFromString, encode } = require('@glif/filecoin-address')
+const {
+  decode,
+  encode,
+  CoinType,
+  delegatedFromEthAddress,
+  ethAddressFromDelegated
+} = require('@glif/filecoin-address')
 
-const address = newFromString('t1hvuzpfdycc6z6mjgbiyaiojikd6wk2vwy7muuei')
+const address = decode('t1hvuzpfdycc6z6mjgbiyaiojikd6wk2vwy7muuei')
 const addressProtocol = address.protocol()
 const addressPayload = address.payload()
-const addressString = address.str // Uint8Array
+const addressBytes = address.bytes // Uint8Array
+const addressString = address.toString()
 
-const networkPrefix = 't'
-const encoded = encode(networkPrefix, address)
+const encoded = encode(CoinType.TEST, address)
+
+const delegated = delegatedFromEthAddress(
+  '0x52963EF50e27e06D72D59fcB4F3c2a687BE3cfEf',
+  CoinType.TEST
+)
+const ethAddress = ethAddressFromDelegated(delegated)
 ```
 
-#### Exported methods
-
-- newAddress
-- newIDAddress
-- newFromString
-- decode
-- encode
-- equals
-- bigintToArray
-- getChecksum
-- validateChecksum
-- validateAddressString
-- checkAddressString
+## API
+
+### Enums and types
+
+- `CoinType` / `Network`: `'f'` (mainnet) and `'t'` (testnet)
+- `Protocol`: `ID`, `SECP256K1`, `ACTOR`, `BLS`, `DELEGATED`
+- `DelegatedNamespace`: currently `EVM = 10`
+- `EthAddress`: type alias for `0x...` hex Ethereum addresses
+- `AddressData`: parsed address metadata returned by `checkAddressString`
+
+### `Address` class
+
+- `new Address(bytes, coinType?)`
+- Instance members:
+  - `bytes`
+  - `network()`
+  - `coinType()`
+  - `protocol()`
+  - `payload()`
+  - `namespaceLength` (delegated only)
+  - `namespace` (delegated only)
+  - `subAddr` (delegated only)
+  - `subAddrHex` (delegated only)
+  - `toString()`
+  - `equals(address)`
+
+### Address constructors
+
+- `newAddress(protocol, payload, coinType?)`
+- `newIDAddress(id, coinType?)`
+- `newActorAddress(data, coinType?)`
+- `newSecp256k1Address(pubkey, coinType?)`
+- `newBLSAddress(pubkey, coinType?)`
+- `newDelegatedAddress(namespace, subAddr, coinType?)`
+- `newDelegatedEthAddress(ethAddr, coinType?)`
+
+### Parse, encode, and validation helpers
+
+- `decode(address)` (alias: `newFromString(address)`)
+- `encode(coinType, address)`
+- `validateAddressString(addressString)`
+- `checkAddressString(addressString)`
+- `bigintToArray(value)`
+- `getChecksum(data)`
+- `validateChecksum(data, checksum)`
+
+### ID and FEVM/EVM helpers
+
+- `idFromAddress(address)`
+- `idFromPayload(payload)`
+- `delegatedFromEthAddress(ethAddr, coinType?)`
+- `ethAddressFromDelegated(delegatedAddress)`
+- `isEthAddress(address)`
+- `isEthIdMaskAddress(ethAddr)`
+- `idFromEthAddress(ethAddr, coinType?)`
+- `ethAddressFromID(idAddress)`
 
 ## Test