Merge pull request #36 from hgraph-io/erc

add erc20 support

Author: tmctl

README.md

@@ -171,6 +171,11 @@ This command initiates a WebSocket connection to the GraphQL endpoint at `wss://
 npm install -g wscat
 ```
 
+## Token Helpers (ERC-20 & ERC-721)
+
+The SDK provides simple wrappers around standard token contracts using `ethers.js`.
+See [`src/tokens/README.md`](src/tokens/README.md) for full examples.
+
 ## Versioning
 
 This Software Development Kit (SDK) is actively being developed in conjunction with the [Hgraph API](https://hgraph.com) to ensure seamless integration and compatibility between the two. We are committed to adopting [Semantic Versioning](https://semver.org) standards, which will provide clear and predictable updates, making it easier for developers to manage dependencies and stay informed about changes.

src/index.ts

@@ -4,3 +4,4 @@ export {default as default} from './client'
 export {HgraphContract} from './contract'
 export {useHgraph} from './hooks/useHgraph'
 export {HgraphProvider} from './context/HgraphProvider'
+export * from './tokens'

src/tokens/README.md

@@ -0,0 +1,30 @@
+# Token Helpers
+
+The SDK ships with lightweight wrappers around standard ERC-20 and ERC-721 contracts. Each wrapper uses `ethers.js` under the hood and exposes common methods so you can easily integrate token functionality in your application.
+
+## ERC-20
+
+```typescript
+import {ERC20} from '@hgraph.io/sdk'
+import {JsonRpcProvider} from 'ethers'
+
+const provider = new JsonRpcProvider('https://your.rpc.url')
+const token = new ERC20('0xTokenAddress', provider)
+
+const balance = await token.balanceOf('0xAccount')
+await token.transfer('0xRecipient', 100n)
+```
+
+## ERC-721
+
+```typescript
+import {ERC721} from '@hgraph.io/sdk'
+import {JsonRpcProvider} from 'ethers'
+
+const provider = new JsonRpcProvider('https://your.rpc.url')
+const nft = new ERC721('0xCollectionAddress', provider)
+
+const owner = await nft.ownerOf(1n)
+const uri = await nft.tokenURI(1n)
+await nft.safeTransferFrom('0xOwner', '0xReceiver', 1n)
+```

src/tokens/erc20.ts

@@ -0,0 +1,42 @@
+import {Contract, type ContractRunner, type InterfaceAbi, type BigNumberish, type TransactionResponse} from 'ethers'
+
+export const ERC20_ABI: InterfaceAbi = [
+  'function name() view returns (string)',
+  'function symbol() view returns (string)',
+  'function decimals() view returns (uint8)',
+  'function balanceOf(address account) view returns (uint256)',
+  'function transfer(address to, uint256 amount) returns (bool)',
+  'function transferFrom(address from, address to, uint256 amount) returns (bool)',
+]
+
+export default class ERC20 {
+  public contract: Contract
+
+  constructor(address: string, runner: ContractRunner) {
+    this.contract = new Contract(address, ERC20_ABI, runner)
+  }
+
+  name(): Promise<string> {
+    return this.contract.name()
+  }
+
+  symbol(): Promise<string> {
+    return this.contract.symbol()
+  }
+
+  decimals(): Promise<number> {
+    return this.contract.decimals()
+  }
+
+  balanceOf(account: string): Promise<bigint> {
+    return this.contract.balanceOf(account)
+  }
+
+  transfer(to: string, amount: BigNumberish): Promise<TransactionResponse> {
+    return this.contract.transfer(to, amount)
+  }
+
+  transferFrom(from: string, to: string, amount: BigNumberish): Promise<TransactionResponse> {
+    return this.contract.transferFrom(from, to, amount)
+  }
+}

src/tokens/erc721.ts

@@ -0,0 +1,42 @@
+import {Contract, type ContractRunner, type InterfaceAbi, type BigNumberish, type TransactionResponse} from 'ethers'
+
+export const ERC721_ABI: InterfaceAbi = [
+  'function name() view returns (string)',
+  'function symbol() view returns (string)',
+  'function ownerOf(uint256 tokenId) view returns (address)',
+  'function tokenURI(uint256 tokenId) view returns (string)',
+  'function transferFrom(address from, address to, uint256 tokenId)',
+  'function safeTransferFrom(address from, address to, uint256 tokenId)',
+]
+
+export default class ERC721 {
+  public contract: Contract
+
+  constructor(address: string, runner: ContractRunner) {
+    this.contract = new Contract(address, ERC721_ABI, runner)
+  }
+
+  name(): Promise<string> {
+    return this.contract.name()
+  }
+
+  symbol(): Promise<string> {
+    return this.contract.symbol()
+  }
+
+  ownerOf(tokenId: BigNumberish): Promise<string> {
+    return this.contract.ownerOf(tokenId)
+  }
+
+  tokenURI(tokenId: BigNumberish): Promise<string> {
+    return this.contract.tokenURI(tokenId)
+  }
+
+  transferFrom(from: string, to: string, tokenId: BigNumberish): Promise<TransactionResponse> {
+    return this.contract.transferFrom(from, to, tokenId)
+  }
+
+  safeTransferFrom(from: string, to: string, tokenId: BigNumberish): Promise<TransactionResponse> {
+    return this.contract.safeTransferFrom(from, to, tokenId)
+  }
+}

src/tokens/index.ts

@@ -0,0 +1,2 @@
+export {default as ERC20, ERC20_ABI} from './erc20'
+export {default as ERC721, ERC721_ABI} from './erc721'

src/types/index.ts

@@ -4,6 +4,9 @@ import {
   Contract as EthersContract,
   InterfaceAbi,
   LogDescription as EventLogDescription,
+  type ContractRunner,
+  type BigNumberish,
+  type TransactionResponse,
 } from 'ethers'
 import {DocumentNode} from 'graphql/language/ast'
 import {Client as SubscriptionClient} from '../../graphql-ws/src'
@@ -154,6 +157,50 @@ export declare class HgraphContract {
   ) => Promise<EventLogDescription[]>
 }
 
+/*
+ * ERC-20
+ */
+export declare const ERC20_ABI: InterfaceAbi
+
+export declare class ERC20 {
+  public contract: EthersContract
+  constructor(address: string, runner: ContractRunner)
+  name(): Promise<string>
+  symbol(): Promise<string>
+  decimals(): Promise<number>
+  balanceOf(account: string): Promise<bigint>
+  transfer(to: string, amount: BigNumberish): Promise<TransactionResponse>
+  transferFrom(
+    from: string,
+    to: string,
+    amount: BigNumberish
+  ): Promise<TransactionResponse>
+}
+
+/*
+ * ERC-721
+ */
+export declare const ERC721_ABI: InterfaceAbi
+
+export declare class ERC721 {
+  public contract: EthersContract
+  constructor(address: string, runner: ContractRunner)
+  name(): Promise<string>
+  symbol(): Promise<string>
+  ownerOf(tokenId: BigNumberish): Promise<string>
+  tokenURI(tokenId: BigNumberish): Promise<string>
+  transferFrom(
+    from: string,
+    to: string,
+    tokenId: BigNumberish
+  ): Promise<TransactionResponse>
+  safeTransferFrom(
+    from: string,
+    to: string,
+    tokenId: BigNumberish
+  ): Promise<TransactionResponse>
+}
+
 /*
  * Requests
  */

tests/ERC20.test.ts

@@ -0,0 +1,31 @@
+import {describe, it, expect, vi} from 'vitest'
+import ERC20 from '../src/tokens/erc20'
+
+describe('ERC20 wrapper', () => {
+  it('calls underlying contract methods', async () => {
+    const token = new ERC20('0x0', {} as any)
+    const mock = {
+      name: vi.fn().mockResolvedValue('Token'),
+      symbol: vi.fn().mockResolvedValue('TKN'),
+      decimals: vi.fn().mockResolvedValue(18),
+      balanceOf: vi.fn().mockResolvedValue(5n),
+      transfer: vi.fn().mockResolvedValue('tx1'),
+      transferFrom: vi.fn().mockResolvedValue('tx2'),
+    }
+    ;(token as any).contract = mock
+
+    expect(await token.name()).toBe('Token')
+    expect(await token.symbol()).toBe('TKN')
+    expect(await token.decimals()).toBe(18)
+    expect(await token.balanceOf('0xabc')).toBe(5n)
+    await token.transfer('0xdef', 1n)
+    await token.transferFrom('0xabc', '0xdef', 2n)
+
+    expect(mock.name).toHaveBeenCalled()
+    expect(mock.symbol).toHaveBeenCalled()
+    expect(mock.decimals).toHaveBeenCalled()
+    expect(mock.balanceOf).toHaveBeenCalledWith('0xabc')
+    expect(mock.transfer).toHaveBeenCalledWith('0xdef', 1n)
+    expect(mock.transferFrom).toHaveBeenCalledWith('0xabc', '0xdef', 2n)
+  })
+})

tests/ERC721.test.ts

@@ -0,0 +1,31 @@
+import {describe, it, expect, vi} from 'vitest'
+import ERC721 from '../src/tokens/erc721'
+
+describe('ERC721 wrapper', () => {
+  it('calls underlying contract methods', async () => {
+    const nft = new ERC721('0x0', {} as any)
+    const mock = {
+      name: vi.fn().mockResolvedValue('NFT'),
+      symbol: vi.fn().mockResolvedValue('NFT'),
+      ownerOf: vi.fn().mockResolvedValue('0xabc'),
+      tokenURI: vi.fn().mockResolvedValue('uri'),
+      transferFrom: vi.fn().mockResolvedValue('tx1'),
+      safeTransferFrom: vi.fn().mockResolvedValue('tx2'),
+    }
+    ;(nft as any).contract = mock
+
+    expect(await nft.name()).toBe('NFT')
+    expect(await nft.symbol()).toBe('NFT')
+    expect(await nft.ownerOf(1n)).toBe('0xabc')
+    expect(await nft.tokenURI(1n)).toBe('uri')
+    await nft.transferFrom('0xabc', '0xdef', 1n)
+    await nft.safeTransferFrom('0xabc', '0xdef', 2n)
+
+    expect(mock.name).toHaveBeenCalled()
+    expect(mock.symbol).toHaveBeenCalled()
+    expect(mock.ownerOf).toHaveBeenCalledWith(1n)
+    expect(mock.tokenURI).toHaveBeenCalledWith(1n)
+    expect(mock.transferFrom).toHaveBeenCalledWith('0xabc', '0xdef', 1n)
+    expect(mock.safeTransferFrom).toHaveBeenCalledWith('0xabc', '0xdef', 2n)
+  })
+})