@ledgerhq/coin-hypercore 0.2.0 → 0.4.0

package/src/api/getBalance.test.ts

@@ -0,0 +1,66 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import network from '@ledgerhq/live-network'
+import coinConfig from '../config'
+import { getBalance } from './getBalance'
+
+jest.mock('@ledgerhq/live-network')
+
+const mockNetwork = jest.mocked(network)
+
+beforeAll(() => {
+  coinConfig.setCoinConfig(() => ({
+    node: 'https://perps.live.ledger.com/proxy/perps',
+    status: { type: 'active' },
+  }))
+})
+
+afterEach(() => {
+  mockNetwork.mockClear()
+})
+
+describe('getBalance', () => {
+  it('maps the USDC collateral to a single native balance', async () => {
+    mockNetwork.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        providerId: 'hyperliquid',
+        collateral: { symbol: 'USDC', network: 'hyperliquid' },
+        accountValue: 557.13644,
+        usedMargin: 20,
+        availableBalance: 537.13644,
+        unrealizedPnl: 0,
+      },
+    })
+
+    const balances = await getBalance('0xabc')
+
+    expect(balances).toEqual([
+      {
+        value: 557_136_440n,
+        locked: 20_000_000n,
+        asset: { type: 'native' },
+      },
+    ])
+  })
+
+  it('handles a zero balance without throwing', async () => {
+    mockNetwork.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        providerId: 'hyperliquid',
+        collateral: { symbol: 'USDC', network: 'hyperliquid' },
+        accountValue: 0,
+        usedMargin: 0,
+        availableBalance: 0,
+        unrealizedPnl: 0,
+      },
+    })
+
+    const balances = await getBalance('0xabc')
+
+    expect(balances[0].value).toBe(0n)
+    expect(balances[0].locked).toBe(0n)
+  })
+})

package/src/api/getBalance.ts

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import type { Balance } from '@ledgerhq/coin-module-framework/api/types'
+import { USDC_DECIMALS, fetchBalance } from '../network/yield'
+import { scaleToBigInt } from '../utils'
+
+// The proxy only exposes the USDC collateral, surfaced as the account's native balance:
+// `value` is the total account value, `locked` the margin used by open positions.
+export async function getBalance(address: string): Promise<Balance[]> {
+  const { collateral, accountValue, usedMargin } = await fetchBalance(address)
+  const magnitude = collateral.decimals ?? USDC_DECIMALS
+
+  return [
+    {
+      value: scaleToBigInt(accountValue, magnitude),
+      locked: scaleToBigInt(usedMargin, magnitude),
+      asset: { type: 'native' },
+    },
+  ]
+}

package/src/api/index.integ.test.ts

@@ -3,6 +3,10 @@
 
 import { createApi } from '.'
 
+const NODE = 'https://perps.live.ledger.com/proxy/perps'
+// A real account with USDC collateral and settled fund/withdraw history, for read-only assertions.
+const ADDRESS = '0x90D5b3f3FaA3cd61fBd78bF1CE3DdB2100F4BFb2'
+
 describe('Hypercore Api (Alpaca stub)', () => {
   const api = createApi({ node: 'https://api.hyperliquid.xyz' })
 
@@ -11,8 +15,6 @@ describe('Hypercore Api (Alpaca stub)', () => {
     'getBlockInfo',
     'getBlock',
     'getValidators',
-    'getBalance',
-    'listOperations',
     'getStakes',
     'getRewards',
     'craftTransaction',
@@ -25,6 +27,56 @@ describe('Hypercore Api (Alpaca stub)', () => {
     'validateAddress',
     'craftTransactionData',
   ])('%s throws "not supported"', (name) => {
-    expect(() => (api[name] as (...args: unknown[]) => unknown)()).toThrow('not supported')
+    expect(api[name]).toThrow('not supported')
+  })
+})
+
+describe('Hypercore Api (Alpaca)', () => {
+  const api = createApi({ node: NODE })
+
+  describe('getBalance', () => {
+    it('returns the USDC-denominated account balance', async () => {
+      const balances = await api.getBalance(ADDRESS)
+
+      expect(balances).toHaveLength(1)
+      const [balance] = balances
+      expect(balance.asset.type).toBe('native')
+      expect(typeof balance.value).toBe('bigint')
+      expect(balance.value).toBeGreaterThanOrEqual(0n)
+      expect(balance.locked ?? 0n).toBeGreaterThanOrEqual(0n)
+    })
+  })
+
+  describe('listOperations', () => {
+    it('returns settled deposit/withdraw operations across all pages', async () => {
+      // Small limit to force several pages and exercise cursor chaining end-to-end.
+      const first = await api.listOperations(ADDRESS, { minHeight: 0, limit: 20 })
+      const all = [...first.items]
+      let cursor = first.next
+      while (cursor !== undefined && all.length < 10_000) {
+        const page = await api.listOperations(ADDRESS, { minHeight: 0, cursor, limit: 20 })
+        all.push(...page.items)
+        cursor = page.next
+      }
+
+      expect(all.length).toBeGreaterThan(0)
+      for (const op of all) {
+        expect(['IN', 'OUT']).toContain(op.type)
+        expect(op.senders).toContain(ADDRESS)
+        expect(op.recipients).toContain(ADDRESS)
+        expect(op.value).toBeGreaterThan(0n)
+        expect(op.tx.date).toBeInstanceOf(Date)
+        expect(op.tx.fees).toBe(0n)
+      }
+      // This account has both deposits (IN) and withdrawals (OUT).
+      expect(all.some((op) => op.type === 'IN')).toBe(true)
+      expect(all.some((op) => op.type === 'OUT')).toBe(true)
+    })
+
+    it('rejects a non-zero minHeight', async () => {
+      await expect(api.listOperations(ADDRESS, { minHeight: 1 })).rejects.toThrow(
+        'minHeight is not supported'
+      )
+    })
   })
 })

package/src/api/index.test.ts

@@ -0,0 +1,29 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import { createApi } from '.'
+
+describe('createApi', () => {
+  it('returns all API methods', () => {
+    expect(createApi({ node: 'http://localhost' })).toEqual({
+      broadcast: expect.any(Function),
+      call: expect.any(Function),
+      combine: expect.any(Function),
+      craftRawTransaction: expect.any(Function),
+      craftTransaction: expect.any(Function),
+      craftTransactionData: expect.any(Function),
+      estimateFees: expect.any(Function),
+      getBalance: expect.any(Function),
+      getBlock: expect.any(Function),
+      getBlockInfo: expect.any(Function),
+      getNextSequence: expect.any(Function),
+      getRewards: expect.any(Function),
+      getStakes: expect.any(Function),
+      getValidators: expect.any(Function),
+      lastBlock: expect.any(Function),
+      listOperations: expect.any(Function),
+      validateAddress: expect.any(Function),
+      validateIntent: expect.any(Function),
+    })
+  })
+})

package/src/api/index.ts

@@ -1,12 +1,10 @@
 // SPDX-FileCopyrightText: © 2024 LEDGER SAS
 // SPDX-License-Identifier: Apache-2.0
 
-import type { CoinModuleApi } from '@ledgerhq/coin-module-framework/api/index'
+import { type CoinModuleApi, notSupported } from '@ledgerhq/coin-module-framework/api/index'
 import coinConfig, { type HypercoreConfig } from '../config'
-
-const notSupported = (name: string) => (): never => {
-  throw new Error(`${name} is not supported`)
-}
+import { getBalance } from './getBalance'
+import { listOperations } from './listOperations'
 
 export function createApi(config: HypercoreConfig): CoinModuleApi {
   coinConfig.setCoinConfig(() => ({ ...config, status: { type: 'active' } }))
@@ -15,9 +13,10 @@ export function createApi(config: HypercoreConfig): CoinModuleApi {
     lastBlock: notSupported('lastBlock'),
     getBlockInfo: notSupported('getBlockInfo'),
     getBlock: notSupported('getBlock'),
+    call: notSupported('call'),
     getValidators: notSupported('getValidators'),
-    getBalance: notSupported('getBalance'),
-    listOperations: notSupported('listOperations'),
+    getBalance,
+    listOperations,
     getStakes: notSupported('getStakes'),
     getRewards: notSupported('getRewards'),
     craftTransaction: notSupported('craftTransaction'),

package/src/api/listOperations.test.ts

@@ -0,0 +1,163 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import network from '@ledgerhq/live-network'
+import coinConfig from '../config'
+import { listOperations } from './listOperations'
+
+jest.mock('@ledgerhq/live-network')
+
+const mockNetwork = jest.mocked(network)
+
+const ADDRESS = '0xabc'
+
+beforeAll(() => {
+  coinConfig.setCoinConfig(() => ({
+    node: 'https://perps.live.ledger.com/proxy/perps',
+    status: { type: 'active' },
+  }))
+})
+
+afterEach(() => {
+  mockNetwork.mockClear()
+})
+
+function action(overrides: Record<string, unknown>) {
+  return {
+    id: 'id-1',
+    action: 'fund',
+    status: 'SUCCESS',
+    summary: { amount: '10.5' },
+    createdAt: '2026-01-01T00:00:00.000Z',
+    completedAt: '2026-01-01T00:01:00.000Z',
+    ...overrides,
+  }
+}
+
+describe('listOperations', () => {
+  it('keeps only fund/withdraw actions and maps them to IN/OUT', async () => {
+    mockNetwork.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        total: 3,
+        offset: 0,
+        limit: 100,
+        items: [
+          action({ id: 'dep', action: 'fund', summary: { amount: '10.5' } }),
+          action({ id: 'wit', action: 'withdraw', summary: { amount: '4' } }),
+          action({ id: 'opn', action: 'open', summary: null }),
+        ],
+      },
+    })
+
+    const { items, next } = await listOperations(ADDRESS, { minHeight: 0 })
+
+    expect(items).toHaveLength(2)
+    expect(items[0]).toMatchObject({
+      id: `${ADDRESS}-dep`,
+      type: 'IN',
+      value: 10_500_000n,
+      senders: [ADDRESS],
+      recipients: [ADDRESS],
+      asset: { type: 'native' },
+    })
+    expect(items[0].tx).toMatchObject({ hash: 'dep', fees: 0n, failed: false })
+    expect(items[1]).toMatchObject({ id: `${ADDRESS}-wit`, type: 'OUT', value: 4_000_000n })
+    expect(next).toBeUndefined()
+  })
+
+  it('excludes drafts that never settled (no completedAt)', async () => {
+    mockNetwork.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        total: 2,
+        offset: 0,
+        limit: 100,
+        items: [
+          action({ id: 'settled', completedAt: '2026-01-01T00:01:00.000Z' }),
+          action({ id: 'draft', status: 'CREATED', completedAt: null }),
+        ],
+      },
+    })
+
+    const { items } = await listOperations(ADDRESS, { minHeight: 0 })
+
+    expect(items).toHaveLength(1)
+    expect(items[0].id).toBe(`${ADDRESS}-settled`)
+  })
+
+  it('marks failed actions', async () => {
+    mockNetwork.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        total: 1,
+        offset: 0,
+        limit: 100,
+        items: [action({ id: 'dep', status: 'FAILED' })],
+      },
+    })
+
+    const { items } = await listOperations(ADDRESS, { minHeight: 0 })
+
+    expect(items[0].tx.failed).toBe(true)
+  })
+
+  it('computes the next cursor from the raw page size and total', async () => {
+    mockNetwork.mockResolvedValueOnce({
+      status: 200,
+      data: {
+        total: 10,
+        offset: 0,
+        limit: 2,
+        items: [action({ id: 'a' }), action({ id: 'b', action: 'open', summary: null })],
+      },
+    })
+
+    const { items, next } = await listOperations(ADDRESS, { minHeight: 0, limit: 2 })
+
+    // Only one fund/withdraw kept, but the cursor advances by the two raw items consumed.
+    expect(items).toHaveLength(1)
+    expect(next).toBe('2')
+    expect(mockNetwork).toHaveBeenCalledWith(
+      expect.objectContaining({
+        params: { address: ADDRESS, offset: 0, limit: 2, providerId: 'hyperliquid' },
+      })
+    )
+  })
+
+  it('passes the cursor as offset on subsequent pages', async () => {
+    mockNetwork.mockResolvedValueOnce({
+      status: 200,
+      data: { total: 10, offset: 2, limit: 2, items: [] },
+    })
+
+    await listOperations(ADDRESS, { minHeight: 0, cursor: '2', limit: 2 })
+
+    expect(mockNetwork).toHaveBeenCalledWith(
+      expect.objectContaining({
+        params: { address: ADDRESS, offset: 2, limit: 2, providerId: 'hyperliquid' },
+      })
+    )
+  })
+
+  it('rejects a non-zero minHeight', async () => {
+    await expect(listOperations(ADDRESS, { minHeight: 5 })).rejects.toThrow(
+      'minHeight is not supported'
+    )
+    expect(mockNetwork).not.toHaveBeenCalled()
+  })
+
+  it('rejects an ascending order', async () => {
+    await expect(listOperations(ADDRESS, { minHeight: 0, order: 'asc' })).rejects.toThrow(
+      'ascending order is not supported'
+    )
+    expect(mockNetwork).not.toHaveBeenCalled()
+  })
+
+  it('rejects an invalid cursor', async () => {
+    await expect(listOperations(ADDRESS, { minHeight: 0, cursor: 'not-a-number' })).rejects.toThrow(
+      'invalid cursor'
+    )
+    expect(mockNetwork).not.toHaveBeenCalled()
+  })
+})

package/src/api/listOperations.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+  ListOperationsOptions,
+  Operation,
+  Page,
+} from '@ledgerhq/coin-module-framework/api/types'
+import {
+  type ActionDto,
+  FUND_ACTION,
+  USDC_DECIMALS,
+  WITHDRAW_ACTION,
+  fetchActions,
+} from '../network/yield'
+import { scaleToBigInt } from '../utils'
+
+const DEFAULT_LIMIT = 100
+
+// Deposits/withdrawals that actually settled — drafts (status CREATED) have no completedAt.
+function isSettledTransfer(action: ActionDto): boolean {
+  const isTransfer = action.action === FUND_ACTION || action.action === WITHDRAW_ACTION
+  return isTransfer && action.completedAt !== null
+}
+
+function toOperation(address: string, dto: ActionDto): Operation {
+  const isDeposit = dto.action === FUND_ACTION
+  const amount = dto.summary?.amount ?? '0'
+  const date = new Date(dto.completedAt ?? dto.createdAt)
+
+  return {
+    id: `${address}-${dto.id}`,
+    type: isDeposit ? 'IN' : 'OUT',
+    senders: [address],
+    recipients: [address],
+    value: scaleToBigInt(amount, USDC_DECIMALS),
+    asset: { type: 'native' },
+    tx: {
+      hash: dto.id,
+      // HyperCore actions have no block height on this API.
+      block: { height: 0, hash: '', time: date },
+      fees: 0n,
+      date,
+      failed: dto.status.toUpperCase() === 'FAILED',
+    },
+  }
+}
+
+// The proxy only supports offset pagination, so the cursor is the numeric offset.
+function parseCursor(cursor: string | undefined): number {
+  if (cursor === undefined) return 0
+  const offset = Number(cursor)
+  if (!Number.isInteger(offset) || offset < 0) {
+    throw new Error(`listOperations received an invalid cursor: ${cursor}`)
+  }
+  return offset
+}
+
+export async function listOperations(
+  address: string,
+  { minHeight, cursor, limit, order }: ListOperationsOptions
+): Promise<Page<Operation>> {
+  // The proxy has no block height and always returns actions newest-first (descending).
+  if (minHeight > 0) {
+    throw new Error('listOperations with a minHeight is not supported')
+  }
+  if (order === 'asc') {
+    throw new Error('listOperations with an ascending order is not supported')
+  }
+
+  const offset = parseCursor(cursor)
+  const pageLimit = limit ?? DEFAULT_LIMIT
+  const page = await fetchActions(address, offset, pageLimit)
+
+  const items = page.items.filter(isSettledTransfer).map((action) => toOperation(address, action))
+
+  // Advance by raw items consumed, not the filtered count, so no action is skipped.
+  // The cursor is offset-based (volatile if new actions appear between calls); the proxy
+  // exposes no stable id/date-based pagination.
+  const nextOffset = offset + page.items.length
+  const next = nextOffset < page.total ? String(nextOffset) : undefined
+
+  return { items, next }
+}

package/src/network/yield.test.ts

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import network from '@ledgerhq/live-network'
+import coinConfig from '../config'
+import { fetchBalance, fetchActions } from './yield'
+
+jest.mock('@ledgerhq/live-network')
+
+const mockNetwork = jest.mocked(network)
+
+const BASE_CONFIG = { node: 'https://perps.live.ledger.com/proxy/perps' }
+
+beforeAll(() => {
+  coinConfig.setCoinConfig(() => ({ ...BASE_CONFIG, status: { type: 'active' } }))
+})
+
+afterEach(() => {
+  mockNetwork.mockClear()
+})
+
+const COLLATERAL = {
+  symbol: 'USDC',
+  name: 'USD Coin',
+  network: 'arbitrum',
+  decimals: 6,
+  address: null,
+  logoURI: null,
+}
+
+describe('fetchBalance', () => {
+  it('calls POST /v1/balances with correct args', async () => {
+    const dto = {
+      providerId: 'hyperliquid',
+      collateral: COLLATERAL,
+      accountValue: 100,
+      usedMargin: 20,
+      availableBalance: 80,
+      unrealizedPnl: 5,
+    }
+    mockNetwork.mockResolvedValueOnce({ status: 200, data: dto })
+
+    const result = await fetchBalance('0xabc')
+
+    expect(mockNetwork).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: 'POST',
+        url: 'https://perps.live.ledger.com/proxy/perps/v1/balances',
+        data: { providerId: 'hyperliquid', address: '0xabc' },
+      })
+    )
+    expect(result).toEqual(dto)
+  })
+})
+
+describe('fetchActions', () => {
+  it('calls GET /v1/actions with correct args', async () => {
+    const dto = { total: 0, offset: 10, limit: 100, items: [] }
+    mockNetwork.mockResolvedValueOnce({ status: 200, data: dto })
+
+    const result = await fetchActions('0xabc', 10, 100)
+
+    expect(mockNetwork).toHaveBeenCalledWith(
+      expect.objectContaining({
+        method: 'GET',
+        url: 'https://perps.live.ledger.com/proxy/perps/v1/actions',
+        params: { address: '0xabc', offset: 10, limit: 100, providerId: 'hyperliquid' },
+      })
+    )
+    expect(result).toEqual(dto)
+  })
+})

package/src/network/yield.ts

@@ -0,0 +1,72 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import network from '@ledgerhq/live-network'
+import coinConfig from '../config'
+
+const PROVIDER_ID = 'hyperliquid'
+const getBaseUrl = () => coinConfig.getCoinConfig().node
+
+// The collateral is USDC and the proxy omits its decimals.
+export const USDC_DECIMALS = 6
+// A deposit is the `fund` action, a withdrawal the `withdraw` action.
+export const FUND_ACTION = 'fund'
+export const WITHDRAW_ACTION = 'withdraw'
+
+export type TokenDto = {
+  symbol: string
+  network: string
+  // The proxy omits these fields for the perps collateral, so they are optional.
+  name?: string
+  decimals?: number
+  address?: string | null
+  logoURI?: string | null
+}
+
+export type YieldBalanceDto = {
+  providerId: string
+  collateral: TokenDto
+  accountValue: number
+  usedMargin: number
+  availableBalance: number
+  unrealizedPnl: number
+}
+
+export async function fetchBalance(address: string): Promise<YieldBalanceDto> {
+  const { data } = await network<YieldBalanceDto>({
+    method: 'POST',
+    url: `${getBaseUrl()}/v1/balances`,
+    data: { providerId: PROVIDER_ID, address },
+  })
+  return data
+}
+
+export type ActionDto = {
+  id: string
+  action: string
+  status: string
+  // `summary` is null for some action types.
+  summary: { amount: string } | null
+  createdAt: string
+  completedAt: string | null
+}
+
+export type ActionsPage = {
+  total: number
+  offset: number
+  limit: number
+  items: ActionDto[]
+}
+
+export async function fetchActions(
+  address: string,
+  offset: number,
+  limit: number
+): Promise<ActionsPage> {
+  const { data } = await network<ActionsPage>({
+    method: 'GET',
+    url: `${getBaseUrl()}/v1/actions`,
+    params: { address, offset, limit, providerId: PROVIDER_ID },
+  })
+  return data
+}

package/src/utils/index.test.ts

@@ -0,0 +1,20 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import { scaleToBigInt } from '.'
+
+describe('scaleToBigInt', () => {
+  it.each([
+    ['557.13644', 6, 557_136_440n],
+    [557.13644, 6, 557_136_440n],
+    ['0', 6, 0n],
+    [0, 6, 0n],
+    ['10', 6, 10_000_000n],
+    ['0.000001', 6, 1n],
+    // extra fractional digits are rounded (framework uses BigNumber.integerValue)
+    ['1.2345678', 6, 1_234_568n],
+    ['-3.5', 6, -3_500_000n],
+  ])('scales %s with %i decimals', (amount, magnitude, expected) => {
+    expect(scaleToBigInt(amount, magnitude)).toBe(expected)
+  })
+})

package/src/utils/index.ts

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: © 2024 LEDGER SAS
+// SPDX-License-Identifier: Apache-2.0
+
+import { parseCurrencyUnit } from '@ledgerhq/coin-module-framework/currencies'
+
+// Convert a decimal amount into its integer base-unit representation.
+export function scaleToBigInt(amount: string | number, magnitude: number): bigint {
+  return BigInt(parseCurrencyUnit({ name: '', code: '', magnitude }, String(amount)).toFixed())
+}