@ledgerhq/coin-module-framework 0.1.9

package/.eslintrc.js

@@ -0,0 +1,20 @@
+module.exports = {
+  env: {
+    browser: true,
+    es6: true,
+  },
+  overrides: [
+    {
+      files: ["src/**/*.test.{ts,tsx}"],
+      env: {
+        "jest/globals": true,
+      },
+      plugins: ["jest"],
+    },
+  ],
+  rules: {
+    "no-console": ["error", { allow: ["warn", "error"] }],
+    "@typescript-eslint/no-empty-function": "off",
+    "@typescript-eslint/no-explicit-any": "warn",
+  },
+};

package/.unimportedrc.json

@@ -0,0 +1,33 @@
+{
+  "entry": [
+    "src/api/index.ts",
+    "src/currencies/index.ts",
+    "src/index.ts",
+    "src/utils.ts"
+  ],
+  "ignoreUnimported": [
+    "src/api/errors.ts",
+    "src/api/index.ts",
+    "src/api/types.ts",
+    "src/config.ts",
+    "src/currencies/formatCurrencyUnit.ts",
+    "src/currencies/index.ts",
+    "src/currencies/parseCurrencyUnit.ts",
+    "src/errors.ts",
+    "src/features/types.ts",
+    "src/setup.ts",
+    "src/test/utils.ts",
+    "src/utils.ts"
+  ],
+  "ignoreUnresolved": [
+    "src/features/types.ts",
+    "src/setup.ts",
+    "src/utils.ts"
+  ],
+  "ignoreUnused": [
+    "@ledgerhq/errors",
+    "@ledgerhq/live-env",
+    "@ledgerhq/types-cryptoassets",
+    "expect"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1 @@
+# @ledgerhq/coin-module-framework

package/jest-global-setup.js

@@ -0,0 +1,9 @@
+module.exports = async () => {
+  /**
+   * Set the timezone to EST for all tests
+   * This allow us to run tests directly through jest without having to manually
+   * set the timezone as an env var beforehand, either manually or through a
+   * custom script in package.json
+   */
+  process.env.TZ = "America/New_York";
+};

package/jest.config.js

@@ -0,0 +1,30 @@
+module.exports = {
+  testEnvironment: "node",
+  transform: {
+    "^.+\\.(t|j)sx?$": [
+      "@swc/jest",
+      {
+        jsc: {
+          target: "esnext",
+        },
+      },
+    ],
+  },
+  testPathIgnorePatterns: ["lib/", "lib-es/"],
+  globalSetup: "<rootDir>/jest-global-setup.js",
+  passWithNoTests: true,
+  collectCoverageFrom: [
+    "src/**/*.{ts,js,tsx}",
+    "!src/**/*.test.{ts,tsx}",
+    "!src/**/*.spec.{ts,tsx}",
+    "!src/**/__integration__/**",
+    "!src/**/__integrations__/**",
+    "!src/**/__tests__/**",
+  ],
+  coverageReporters: ["json", ["lcov", { file: "lcov.info", projectRoot: "../../" }], "text"],
+  reporters: [
+    "default",
+    ["jest-sonar", { outputName: "sonar-executionTests-report.xml", reportedFilePath: "absolute" }],
+  ],
+  setupFilesAfterEnv: ["<rootDir>/src/setup.ts"],
+};

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@ledgerhq/coin-module-framework",
+  "version": "0.1.9",
+  "description": "Ledger framework for Coin integration",
+  "keywords": [
+    "Ledger",
+    "LedgerWallet",
+    "Hardware Wallet"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LedgerHQ/alpaca-coin-module"
+  },
+  "bugs": {
+    "url": "https://github.com/LedgerHQ/alpaca-coin-module/issues"
+  },
+  "homepage": "https://github.com/LedgerHQ/alpaca-coin-module/tree/develop/libs/coin-module-framework",
+  "publishConfig": {
+    "access": "public"
+  },
+  "typesVersions": {
+    "*": {
+      "lib/*": [
+        "lib/*"
+      ],
+      "lib-es/*": [
+        "lib-es/*"
+      ],
+      "currencies": [
+        "lib/currencies/index"
+      ],
+      "*": [
+        "lib/*"
+      ]
+    }
+  },
+  "exports": {
+    "./lib/*": "./lib/*.js",
+    "./lib-es/*": "./lib-es/*.js",
+    "./currencies": {
+      "@ledgerhq/source": "./src/currencies/index.ts",
+      "require": "./lib/currencies/index.js",
+      "default": "./lib-es/currencies/index.js"
+    },
+    "./*": {
+      "@ledgerhq/source": "./src/*.ts",
+      "require": "./lib/*.js",
+      "default": "./lib-es/*.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@ledgerhq/errors": "6.31.0-nightly.20260317030141",
+    "@ledgerhq/live-env": "2.30.0-nightly.20260317030141",
+    "@ledgerhq/live-currency-format": "0.6.0-nightly.20260317030141",
+    "@ledgerhq/types-cryptoassets": "7.35.0-nightly.20260317030141",
+    "bignumber.js": "^9.1.2"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/jest": "^30.0.0",
+    "cross-env": "^7.0.3",
+    "jest": "^30.2.0",
+    "@swc/jest": "0.2.39",
+    "@swc/core": "1.15.11"
+  },
+  "scripts": {
+    "clean": "rm -rf lib lib-es",
+    "build": "tsc --project tsconfig.build.json && tsc --project tsconfig.build.json -m esnext --moduleResolution bundler --outDir lib-es",
+    "coverage": "jest --coverage",
+    "prewatch": "pnpm build",
+    "watch": "tsc --watch --project tsconfig.build.json",
+    "watch:es": "tsc --watch --project tsconfig.build.json -m esnext --moduleResolution bundler --outDir lib-es",
+    "lint": "eslint ./src --no-error-on-unmatched-pattern --ext .ts,.tsx --cache",
+    "lint:fix": "pnpm lint --fix",
+    "test": "cross-env TZ=America/Paris jest",
+    "test:debug": "cross-env TZ=America/Paris node --inspect-brk ./node_modules/jest/bin/jest.js --runInBand",
+    "unimported": "unimported",
+    "update:deps": "../../bin/update-coin-module-deps.sh"
+  }
+}

package/src/api/errors.ts

@@ -0,0 +1,5 @@
+export class IncorrectTypeError extends Error {
+  constructor(message?: string) {
+    super(`IncorrectType: ${message}`)
+  }
+}

package/src/api/index.ts

@@ -0,0 +1,7 @@
+/**
+ * Module related to all API exposition constraints and helper.
+ * One consumer of this API is Alpaca.
+ */
+
+export * from './errors'
+export * from './types'

package/src/api/types.ts

@@ -0,0 +1,726 @@
+// NOTE: from types-live
+export type BroadcastConfig = {
+  mevProtected: boolean
+  sponsored?: boolean
+  source?: TransactionSource
+}
+
+/**
+ * TransactionSource identifies the origin of a transaction
+ */
+export type TransactionSource = {
+  // Type of the transaction source
+  type: 'dApp' | 'live-app' | 'coin-module' | 'swap'
+  // Name/identifier of the source (e.g., manifestId, provider name)
+  name: string
+}
+
+export type BlockInfo = {
+  height: number
+  hash: string
+  // can be different from tx date
+  // transaction could be created at a particular moment, but depending on network conditions
+  // mining time, and block intervals, it might not get included in the blockchain until later
+  time: Date
+  parent?: ParentBlock
+}
+
+export type ParentBlock = Pick<BlockInfo, 'height' | 'hash'>
+
+// NOTE: from crypto-asset
+export type Unit = {
+  // display name of a given unit (example: satoshi)
+  name: string
+  // string to use when formatting the unit. like 'BTC' or 'USD'
+  code: string
+  // number of digits after the '.'
+  magnitude: number
+  // should it always print all digits even if they are 0 (usually: true for fiats, false for cryptos)
+  showAllDigits?: boolean
+  // true if the code should prefix amount when formatting
+  prefixCode?: boolean
+}
+
+export type AssetInfo =
+  | { type: 'native'; name?: string; unit?: Unit }
+  | {
+      type: string // token, coin, fungible_asset, trc10, trc20, erc20, erc721, erc1155, etc.
+      assetReference?: string // contract address (trc20), tokenId (trc10),, etc
+      assetOwner?: string // Address of the asset contract deployer/creator
+      name?: string // e.g., token name, or asset name
+      unit?: Unit
+    }
+
+// NOTE: CoreOperation
+export type Operation<MemoType extends Memo = MemoNotSupported> = {
+  id: string
+  type: string
+
+  senders: string[]
+  recipients: string[]
+
+  value: bigint
+  asset: AssetInfo
+
+  /**
+   * Optional memo associated with the operation.
+   * Use a `Memo` interface like `StringMemo<"text">`, `MapMemo<Kind, Value>`, or `MyMemo`.
+   * Defaults to `MemoNotSupported`.
+   */
+  memo?: MemoType
+
+  /**
+   * Arbitrary per-blockchain extra fields.
+   * This can include things like status, error messages, swap info, etc.
+   */
+  details?: Record<string, unknown>
+  tx: {
+    hash: string // transaction hash
+    block: BlockInfo // block metadata, empty string for block hash if not available directly and no reorg possible
+    fees: bigint // network fees paid
+    // address that paid for this transaction's fees.
+    // optional as it may be unknown (e.g. the information is not available in the context of the operation).
+    // if it is unknown, it's expected that none of the sender addresses paid for the fees
+    feesPayer?: string
+    date: Date // tx date (may differ from block time)
+
+    /** If the transaction has failed, fees have been paid but other balance changes are not effective.*/
+    failed: boolean
+  }
+}
+
+export type Transaction = {
+  type: string
+  recipient: string
+  amount: bigint
+  fee: bigint
+} & Record<string, unknown> // Field containing dedicated value for each blockchain
+
+/**
+ * A block along with its {@link BlockTransaction}, not specific to a particular account/address.
+ */
+export type Block = {
+  /** The block metadata. */
+  info: BlockInfo
+
+  /**
+   * The block transactions.
+   *
+   * It should include at least all transactions where an EOA is involved, however it is OK to ignore other types of
+   * transactions that cannot cause balance changes (eg: validator vote transactions on Solana).
+   */
+  transactions: BlockTransaction[]
+}
+
+/**
+ * A transaction belonging to a {@link Block}, not specific to a particular account/address.
+ */
+export type BlockTransaction = {
+  /** The transaction hash/digest (globally unique identifier). */
+  hash: string
+
+  /** If the transaction has been failed, fees have been paid but other balance changes are not effective.*/
+  failed: boolean
+
+  /**
+   * The operations/instructions included in this transaction.
+   *
+   * It should include at least all operations where an EOA is involved, however it is OK to ignore other types of
+   * operations that cannot cause balance changes (eg: validator vote instructions on Solana).
+   *
+   * Note that fees are accounted for separately, so operations must not represent fees.
+   */
+  operations: BlockOperation[]
+
+  /** Network specific details for this transaction. */
+  details?: Record<string, unknown>
+
+  /** The fee amount paid for this transaction, in base unit of the network native coin, always positive or zero.  */
+  fees: bigint
+
+  /** The address that paid for this transaction's fees. */
+  feesPayer?: string
+}
+
+/** An operation belonging to a {@link BlockTransaction}. */
+export type BlockOperation = TransferBlockOperation | OtherBlockOperation
+
+/** An asset transfer that occurred in a {@link BlockTransaction}. */
+export type TransferBlockOperation = {
+  /** Operation type discriminator. */
+  type: 'transfer'
+
+  /** The impacted address (can be sender or recipient based on signum of <code>amount</code>). */
+  address: string
+
+  /** The peer participant in the transfer (optional as it may be not known). */
+  peer?: string
+
+  /** The transferred asset. */
+  asset: AssetInfo
+
+  /**
+   * The signed amount of the transfer, i.e. impact of the transfer on <code>address</code> balance (positive for
+   * incoming, negative for outgoing).
+   */
+  amount: bigint
+}
+
+/**
+ * An unclassified type of operation that occurred in a {@link BlockTransaction}.
+ *
+ * Implementations are free to partially/completely omit this kind of operations.
+ */
+export type OtherBlockOperation = {
+  type: 'other'
+} & Record<string, unknown>
+
+// Other coins take different parameters What do we want to do ?
+export type Account = {
+  currencyName: string
+  address: string
+  balance: bigint
+  currencyUnit: Unit
+  spendableBalance: bigint // NOTE:: check if we can get rid of this one
+}
+
+/**
+ * A component of an account/address balance, for a single asset.
+ *
+ * @see AlpacaApi#getBalance
+ */
+export type Balance = {
+  /** The balance value, in base unit of {@link asset} (always positive). */
+  value: bigint
+
+  /** The balance asset. */
+  asset: AssetInfo
+
+  /** The non-spendable part of {@link value} (eg: minimum balance requirement, or reserved for rent). */
+  locked?: bigint
+
+  /** The {@link Stake} this balance is part of, if any. */
+  stake?: Stake
+}
+
+/** The state of a {@link Stake}. */
+export type StakeState =
+  | 'inactive' // stake has been created/funded, but not collecting any rewards for any reason
+  | 'activating' // stake has been created/funded, and will start collecting rewards on next "epoch" (protocol specific)
+  | 'active' // stake is initialized and collecting rewards
+  | 'deactivating' // stake has been deactivated, will be withdrawable/spendable yet on next "epoch" (protocol specific)
+
+/**
+ * A staking position, for a single address/asset/state.
+ *
+ * Note that on blockchains that allow heterogeneous assets/states in a single account, a staking account is represented
+ * as several {@link Stake}.
+ *
+ * @see Reward
+ * @see AlpacaApi#getStakes
+ */
+export type Stake = {
+  /** An immutable, globally unique id of the stake. Depending on the blockchain, it could simply be the account address,
+   * or a synthetic identifier. */
+  uid: string
+
+  /** The owning account address. Depending on the blockchain, it can be the staking account address or directly the
+   * main one. */
+  address: string
+
+  /** The validator/staking pool/delegate address. */
+  delegate?: string
+
+  /** The stake status, see {@link StakeState}. */
+  state: StakeState
+
+  /** UTC date of last state change. */
+  stateUpdatedAt?: Date
+
+  /** UTC date of initial stake creation. */
+  createdAt?: Date
+
+  /** The staked asset. */
+  asset: AssetInfo
+
+  /** The amount owned by the stake, in base unit of {@link asset} (deposits + rewards). */
+  amount: bigint
+
+  /** The part of {@link amount} that was deposited (<code>amount = amount_deposited + amount_rewarded</code>). */
+  amountDeposited?: bigint
+
+  /** The part of {@link amount} that was rewarded (<code>amount = amount_deposited + amount_rewarded</code>). */
+  amountRewarded?: bigint
+
+  /** A free form map of network specific fields. */
+  details?: Record<string, unknown>
+}
+
+/**
+ * A staking reward distribution event.
+ *
+ * @see Stake
+ * @see AlpacaApi#getRewards
+ */
+export type Reward = {
+  /** {@link Stake#uid} via which this reward was obtained. */
+  stake: string
+
+  /** The reward asset. */
+  asset: AssetInfo
+
+  /** The reward amount. */
+  amount: bigint
+
+  /** UTC date at which reward was effectively credited to the account (not emitted). */
+  receivedAt: Date
+
+  /** If applicable, the transaction hash that distributed the reward. */
+  transactionHash?: string
+
+  /** A free form map of network specific fields. */
+  details?: Record<string, unknown>
+}
+
+/**
+ * Computational payload processed by Blockchains, such as
+ * calldata on EVM or instruction data on Solana
+ */
+export interface TxData {
+  type: string
+}
+
+/**
+ * Default implementation when no computational payload is supported
+ * by the underlying Blockchain
+ */
+export interface TxDataNotSupported extends TxData {
+  type: 'none'
+}
+
+/**
+ * Implementation with bufferized computational payload
+ */
+export interface BufferTxData extends TxData {
+  type: 'buffer'
+  value: Buffer
+}
+
+export interface Memo {
+  type: string
+}
+
+// generic implementations that cover many coins (in coin-framework)
+export interface MemoNotSupported extends Memo {
+  type: 'none'
+}
+
+// Specialized version, not extending the above
+export interface StringMemo<Kind extends string = 'text'> extends Memo {
+  type: 'string'
+  kind: Kind
+  value: string
+}
+
+export interface MapMemo<Kind extends string, Value> extends Memo {
+  type: string
+  memos: Map<Kind, Value>
+}
+
+export interface TypedMapMemo<KindToValueMap extends Record<string, unknown>> extends Memo {
+  type: string
+  memos: Map<keyof KindToValueMap, KindToValueMap[keyof KindToValueMap]>
+}
+
+type MaybeMemo<MemoType extends Memo> = MemoType extends MemoNotSupported
+  ? object
+  : { memo: MemoType }
+
+type MaybeTxData<TxDataType extends TxData> = TxDataType extends TxDataNotSupported
+  ? object
+  : { data: TxDataType }
+
+export type FeesStrategy = 'slow' | 'medium' | 'fast' | 'custom'
+
+export type StakingOperation = 'delegate' | 'undelegate' | 'redelegate'
+
+export type TransactionIntent<
+  MemoType extends Memo = MemoNotSupported,
+  TxDataType extends TxData = TxDataNotSupported,
+> = {
+  intentType: 'transaction' | 'staking'
+  type: string
+  sender: string
+  recipient: string
+  amount: bigint
+  asset: AssetInfo
+  useAllAmount?: boolean
+  feesStrategy?: FeesStrategy
+  senderPublicKey?: string
+  sequence?: bigint
+  expiration?: number
+  sponsored?: boolean
+} & MaybeMemo<MemoType> &
+  MaybeTxData<TxDataType>
+
+export type StakingTransactionIntent<
+  MemoType extends Memo = MemoNotSupported,
+  TxDataType extends TxData = TxDataNotSupported,
+> = TransactionIntent & {
+  intentType: 'staking'
+  mode: StakingOperation
+  valAddress: string
+  dstValAddress?: string
+} & MaybeMemo<MemoType> &
+  MaybeTxData<TxDataType>
+
+export type SendTransactionIntent<
+  MemoType extends Memo = MemoNotSupported,
+  TxDataType extends TxData = TxDataNotSupported,
+> = TransactionIntent & {
+  intentType: 'transaction'
+} & MaybeMemo<MemoType> &
+  MaybeTxData<TxDataType>
+
+export type TransactionValidation = {
+  errors: Record<string, Error>
+  warnings: Record<string, Error>
+  estimatedFees: bigint
+  totalFees?: bigint
+  amount: bigint
+  totalSpent: bigint
+}
+
+export type FeeEstimation = {
+  value: bigint
+  parameters?: Record<string, unknown>
+}
+
+/** Response of {@link AlpacaApi#craftTransaction}. */
+export type CraftedTransaction = {
+  /** The serialized transaction (encoding is blockchain dependent). */
+  transaction: string
+  /** Blockchain specific details (eg: UTXOs referenced in the transaction). */
+  details?: Record<string, unknown>
+}
+
+/** A pagination cursor. */
+export type Cursor = string
+
+/** A paginated response. */
+export type Page<T> = {
+  items: T[]
+  next?: Cursor | undefined
+}
+
+/** Options for {@link AlpacaApi#listOperations}. */
+export type ListOperationsOptions = {
+  /**
+   * The minimum block height for which to fetch operations (inclusive).
+   *
+   * Implementation must raise a "not supported" error if `minHeight` is non-zero and not supported.
+   */
+  minHeight: number
+
+  /**
+   * A pagination cursor to resume listing.
+   *
+   * Implementation must guarantee the cursor is not volatile, i.e. it can be used long after the last request and still
+   * provide consistent results - for instance, a date or transaction hash.
+   */
+  cursor?: Cursor
+
+  /**
+   * The maximum number of operations to fetch (note this is a soft limit, the implementation may return less or more
+   * operations to not waste RPC calls).
+   *
+   * Implementation must raise a "not supported" error if limit is set and not supported.
+   */
+  limit?: number
+
+  /**
+   * The chronological order of the operations (within one page as well as globally when concatenating all pages).
+   *
+   * Implementation must raise a "not supported" error if order is set and not supported.
+   */
+  order?: 'asc' | 'desc'
+}
+
+/** A network validator */
+export type Validator = {
+  /** Address of the validator. */
+  address: string
+
+  /** Human-readable name of the validator. */
+  name: string
+
+  /** Human-readable description of the validator. */
+  description?: string | undefined
+
+  /** URL of the entity running the validator. */
+  url?: string | undefined
+
+  /** URL of the logo for the validator. */
+  logo?: string | undefined
+
+  /** Amount of native asset in the pool (in base unit of chain native currency). */
+  balance?: bigint | undefined
+
+  /** Validator commission (a bigint serialized as a string). */
+  commissionRate?: string | undefined
+
+  /** Validator Annual Percentage Yield (floating point number between 0 and 1). */
+  apy?: number | undefined
+}
+
+export type AccountInfo = {
+  isNewAccount: boolean
+  balance: string
+  ownerCount: number
+  sequence: number
+}
+
+export type AddressValidationCurrencyParameters = {
+  currencyId: string
+  networkId: number
+}
+
+export type AlpacaApi<
+  MemoType extends Memo = MemoNotSupported,
+  TxDataType extends TxData = TxDataNotSupported,
+> = {
+  // blockchain API
+
+  /**
+   * Get the latest block information from the network.
+   *
+   * This must return the same result as {@link getBlockInfo} for the latest block height.
+   *
+   * @returns the latest block metadata (height, hash, time)
+   * @see getBlockInfo
+   * @see getBlock
+   */
+  lastBlock: () => Promise<BlockInfo>
+
+  /**
+   * Get block information for a specific block height.
+   *
+   * This must return the same result as {@link lastBlock} for the latest block height.
+   *
+   * This API is optional and may not be supported on all networks: implementation should raise a "not supported" error
+   * in such case.
+   *
+   * @param height the block height to query
+   * @returns the block metadata (height, hash, time)
+   * @throws "not supported" if the blockchain does not support querying historical blocks
+   */
+  getBlockInfo: (height: number) => Promise<BlockInfo>
+
+  /**
+   * Get a full block with all its transactions.
+   *
+   * This returns the complete block data including all transactions and their operations.
+   *
+   * This must return the same block info as {@link getBlockInfo} for the same height.
+   *
+   * This API is optional and may not be supported on all networks: implementation should raise a "not supported" error
+   * in such case.
+   *
+   * @param height the block height to query
+   * @returns the complete block with transactions
+   * @throws "not supported" if the blockchain does not support querying full blocks
+   */
+  getBlock: (height: number) => Promise<Block>
+
+  /**
+   * Get the list of validators available on the network.
+   * @param cursor a pagination cursor to resume listing (the implementation must guarantee the cursor is not volatile,
+   *         i.e. it can be used long after the last request and still provide consistent results - for instance,
+   *         a date or transaction hash).
+   *         The concrete implementation may return all validators in a single page when the underlying SDK
+   *         does not provide cursor-based pagination.
+   */
+  getValidators: (cursor?: Cursor) => Promise<Page<Validator>>
+
+  // account read API
+
+  /**
+   * Get the balance(s) for an address/account.
+   *
+   * Returns all asset balances associated with the address, including the native asset and any tokens/sub-assets. Each
+   * balance includes the total value and optionally locked/staked amounts.
+   *
+   * If account is not found, implementation must return an empty balance.
+   *
+   * @param address the account address
+   * @returns an array of balances for all assets held by the address
+   * @see getStakes
+   * @see listOperations
+   */
+  getBalance: (address: string) => Promise<Balance[]>
+
+  /**
+   * List operations for an address/account.
+   *
+   * If account is not found, implementation must return an empty result.
+   *
+   * @param address the owner account address
+   * @param options see {@link ListOperationsOptions}
+   * @returns a page of operations
+   * @see getBalance
+   */
+  listOperations: (address: string, options: ListOperationsOptions) => Promise<Page<Operation>>
+
+  /**
+   * Get staking positions owned by an address/account.
+   *
+   * Results are returned in no particular order, in pages that can be of variable size. Page size is controlled by
+   * implementation and should minimize number of RPC calls (typically by aligning with SDK/RPC API pages).
+   *
+   * Results could include closed/deleted staking positions, this is implementation dependent.
+   *
+   * Since this API can make no sense/be complex to implement/require too many RPC calls on some blockchains, it is
+   * optional: implementation should raise a "not supported" error in such case.
+   *
+   * @param address the owner account address
+   * @param cursor a pagination cursor to resume listing (the implementation must guarantee the cursor is not volatile,
+   *               i.e. it can be used long after the last request and still provide consistent results - for instance,
+   *               a date or transaction hash)
+   * @see getBalance
+   * @see getRewards
+   */
+  getStakes: (address: string, cursor?: Cursor) => Promise<Page<Stake>>
+
+  /**
+   * Get staking reward distribution events since address/account inception.
+   *
+   * Results are returned in ascending chronological order, in pages that can be of variable size. Page size is
+   * controlled by implementation and should minimize number of RPC calls (typically by aligning with SDK/RPC API pages).
+   *
+   * Note that since staking implementations vary from one blockchain to another, some points are implementation dependent:
+   *   - depending on the blockchain account model, the exact meaning of <code>address</code> can be:
+   *      - a parent account => history will include all staking subaccounts
+   *      - a single staking position/subaccount address
+   *   - depending on the reward distribution mechanisms, reward events can be transactions, or blocks/epochs, or
+   *     generated synthetically (eg: daily)
+   *
+   * Since this API can make no sense/be complex to implement/require too many RPC calls on some blockchains, it is
+   * optional: implementation should raise a "not supported" error in such case.
+   *
+   * @param address the account address (see doc, exact scope of the request is implementation dependent)
+   * @param cursor a pagination cursor to resume listing (the implementation must guarantee the cursor is not volatile,
+   *               i.e. it can be used long after the last request and still provide consistent results - for instance,
+   *               a date or transaction hash)
+   * @see getBalance
+   * @see getStakes
+   */
+  getRewards: (address: string, cursor?: Cursor) => Promise<Page<Reward>>
+
+  // transaction API
+
+  /**
+   * Craft an unsigned transaction from a transaction intent.
+   *
+   * The crafted transaction is ready to be signed by the hardware wallet and then combined
+   * with the signature using {@link combine}.
+   *
+   * @param transactionIntent the transaction intent describing what the user wants to do
+   * @param customFees optional custom fees to use instead of the default estimation
+   * @returns the crafted transaction with optional blockchain-specific details
+   * @see craftRawTransaction
+   */
+  craftTransaction: (
+    transactionIntent: TransactionIntent<MemoType, TxDataType>,
+    customFees?: FeeEstimation
+  ) => Promise<CraftedTransaction>
+
+  /**
+   * Craft an unsigned transaction from a raw/pre-built transaction.
+   *
+   * This is an alternative to {@link craftTransaction} for cases where the transaction
+   * is already built externally (e.g., by a dApp or smart contract interaction).
+   *
+   * @param transaction the raw transaction to wrap/prepare for signing
+   * @param sender the sender address
+   * @param publicKey the sender's public key
+   * @param sequence the account sequence/nonce (to prevent replay attacks)
+   * @returns the crafted transaction ready for signing
+   * @throws "not supported" if the blockchain does not support raw transaction crafting
+   * @see craftTransaction
+   */
+  craftRawTransaction: (
+    transaction: string,
+    sender: string,
+    publicKey: string,
+    sequence: bigint
+  ) => Promise<CraftedTransaction>
+
+  /**
+   * Estimate the fees for a transaction intent.
+   *
+   * The estimation should be based on current network conditions (e.g., gas price, fee rate).
+   *
+   * @param transactionIntent the transaction intent describing what the user wants to do
+   * @param customFeesParameters optional blockchain-specific parameters to customize the fee estimation
+   *        (e.g., gas limit, priority fee)
+   * @returns the estimated fees and optional parameters that can be passed to {@link craftTransaction}
+   */
+  estimateFees: (
+    transactionIntent: TransactionIntent<MemoType, TxDataType>,
+    customFeesParameters?: FeeEstimation['parameters']
+  ) => Promise<FeeEstimation>
+
+  /**
+   * Combine a crafted transaction with a signature to produce a signed transaction ready for broadcast.
+   *
+   * @param tx the unsigned/crafted transaction (as returned by {@link craftTransaction})
+   * @param signature the signature produced by the hardware wallet
+   * @param pubkey the public key used to sign (required for some blockchains to verify/embed in the transaction)
+   * @returns the signed transaction ready for {@link broadcast}
+   */
+  combine: (tx: string, signature: string, pubkey?: string) => string | Promise<string>
+
+  /**
+   * Broadcast a signed transaction to the network.
+   *
+   * @param tx the signed transaction (encoding is blockchain dependent, typically hex-encoded)
+   * @param broadcastConfig optional configuration for the broadcast (e.g., retry settings)
+   * @returns the transaction hash/digest once successfully submitted to the network
+   * @throws if the transaction is rejected by the network (e.g., invalid signature, insufficient funds)
+   */
+  broadcast: (tx: string, broadcastConfig?: BroadcastConfig) => Promise<string>
+
+  /**
+   * Validate a transaction intent.
+   *
+   * @param transactionIntent the transaction intent describing what the user wants to do
+   * @param balances current balances of the intent sender
+   * @param customFees optional custom fees to use instead of the default estimation
+   * @returns additional values the intent has been validated with, and optional errors/warnings
+   */
+  validateIntent: (
+    transactionIntent: TransactionIntent<MemoType, TxDataType>,
+    balances: Balance[],
+    customFees?: FeeEstimation
+  ) => Promise<TransactionValidation>
+
+  /**
+   * Get the next sequence number (nonce) for an address
+   *
+   * @param address the account address
+   * @returns the next usable sequence number
+   */
+  getNextSequence: (address: string) => Promise<bigint>
+
+  /**
+   * Validate whether an address is well-formed for the blockchain.
+   *
+   * @param address the address to validate
+   * @param parameters currency-specific validation parameters
+   * @returns `true` if the address is valid, `false` otherwise
+   */
+  validateAddress: (
+    address: string,
+    parameters: Partial<AddressValidationCurrencyParameters>
+  ) => Promise<boolean>
+}

package/src/config.ts

@@ -0,0 +1,81 @@
+import { CryptoCurrency, CryptoCurrencyId } from '@ledgerhq/types-cryptoassets'
+import { MissingCoinConfig } from './errors'
+import type { FeatureConfig } from './features/types'
+
+type ConfigStatus =
+  | {
+      type: 'active'
+      features?: FeatureConfig[]
+    }
+  | {
+      type: 'under_maintenance'
+      message?: string
+    }
+  | {
+      type: 'migration'
+      chain: CryptoCurrencyId
+      from: string
+      to: string
+      link: string
+    }
+  | {
+      type: 'feature_unavailable'
+      link: string
+      feature:
+        | 'history'
+        | 'swap'
+        | 'token_history'
+        | 'send_and_receive'
+        | 'send'
+        | 'receive'
+        | 'sending_tokens'
+        | 'receiving_tokens'
+        | 'staking'
+        | 'claiming_staking_rewards'
+    }
+  | {
+      type: 'will_be_deprecated'
+      deprecated_date: string
+      link: string
+    }
+  | {
+      type: 'deprecated'
+    }
+
+type Banner = {
+  isDisplay: boolean
+  bannerText: string
+  bannerLink?: string
+  bannerLinkText?: string
+}
+
+export type CurrencyConfig = {
+  status: ConfigStatus
+  customBanner?: Banner
+  [key: string]: unknown
+}
+
+export type CoinConfig<T extends CurrencyConfig> = (currency?: CryptoCurrency) => T
+
+function buildCoinConfig<T extends CurrencyConfig>() {
+  let coinConfig: CoinConfig<T> | undefined
+
+  const setCoinConfig = (config: CoinConfig<T>): void => {
+    coinConfig = config
+  }
+
+  const getCoinConfig = (currency?: CryptoCurrency): T => {
+    if (!coinConfig) {
+      throw new MissingCoinConfig()
+    }
+
+    return coinConfig(currency)
+  }
+
+  return {
+    setCoinConfig,
+    getCoinConfig,
+  }
+}
+
+export default buildCoinConfig

package/src/currencies/formatCurrencyUnit.ts

@@ -0,0 +1,6 @@
+export {
+  formatCurrencyUnit,
+  formatCurrencyUnitFragment,
+  type formatCurrencyUnitOptions,
+  type FormatterValue,
+} from '@ledgerhq/live-currency-format'

package/src/currencies/index.ts

@@ -0,0 +1,7 @@
+export { parseCurrencyUnit } from './parseCurrencyUnit'
+export {
+  formatCurrencyUnit,
+  formatCurrencyUnitFragment,
+  type formatCurrencyUnitOptions,
+  type FormatterValue,
+} from './formatCurrencyUnit'

package/src/currencies/parseCurrencyUnit.ts

@@ -0,0 +1 @@
+export { parseCurrencyUnit } from '@ledgerhq/live-currency-format'

package/src/errors.ts

@@ -0,0 +1,4 @@
+import { createCustomErrorClass } from '@ledgerhq/errors'
+
+/** When a coin-module has no CoinConfig setted */
+export const MissingCoinConfig = createCustomErrorClass('MissingCoinConfig')

package/src/features/types.ts

@@ -0,0 +1,66 @@
+/**
+ * Feature IDs as defined in https://ledgerhq.atlassian.net/wiki/spaces/CF/pages/6125551933/Coin+modules+-+ADR-003+-+Features+support
+ * These represent the capabilities/features a coin module can support
+ */
+export type FeatureId =
+  // Blockchain transaction features
+  | 'blockchain_txs'
+  // Staking features
+  | 'staking_txs'
+
+/**
+ * Intent types for blockchain_txs feature
+ */
+export type BlockchainTxsIntent = 'send'
+
+/**
+ * Intent types for staking_txs feature
+ */
+export type StakingTxsIntent = 'delegate' | 'undelegate' | 'redelegate' | 'claimReward' | 'withdraw'
+
+/**
+ * Mapping from feature ID to its supported intents
+ */
+export type FeatureIntentMap = {
+  blockchain_txs: BlockchainTxsIntent
+  staking_txs: StakingTxsIntent
+}
+
+/**
+ * A supported feature declaration in a coin module
+ * Maps feature IDs to their supported intents
+ * Example: { "blockchain_txs": ["send"], "staking_txs": ["delegate", "claimReward"] }
+ */
+export type SupportedFeatures = Partial<Record<FeatureId, string[]>>
+
+/**
+ * Feature status in liveconfig
+ */
+export type FeatureStatus = 'active' | 'inactive'
+
+/**
+ * Feature configuration in liveconfig
+ */
+export type FeatureConfig = {
+  id: FeatureId
+  status: FeatureStatus
+}
+
+/**
+ * Helper function to check if a feature is supported
+ */
+export function hasFeature(supportedFeatures: SupportedFeatures, featureId: FeatureId): boolean {
+  return featureId in supportedFeatures
+}
+
+/**
+ * Helper function to check if an intent is supported for a feature
+ */
+export function hasIntent(
+  supportedFeatures: SupportedFeatures,
+  featureId: FeatureId,
+  intent: string
+): boolean {
+  const intents = supportedFeatures[featureId]
+  return intents?.includes(intent) ?? false
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+import * as api from './api'
+
+export default {
+  api,
+}

package/src/setup.ts

@@ -0,0 +1,4 @@
+import { BigNumber } from 'bignumber.js'
+import { getEnv } from '@ledgerhq/live-env'
+
+BigNumber.set({ DECIMAL_PLACES: getEnv('BIG_NUMBER_DECIMAL_PLACES') })

package/src/test/utils.ts

@@ -0,0 +1,26 @@
+/**
+ * Recursively makes all properties optional.
+ * Arrays keep their element type (but each element is deeply partial).
+ * Primitives and built-in value types (Date, RegExp) are preserved as-is.
+ */
+export type DeepPartial<T> = T extends (infer U)[]
+  ? DeepPartial<U>[]
+  : T extends Date | RegExp
+    ? T
+    : T extends object
+      ? { [K in keyof T]?: DeepPartial<T[K]> }
+      : T
+
+/**
+ * Re-types a function so its return value is wrapped in `Promise<DeepPartial<…>>`,
+ * while keeping the original parameter types intact.
+ *
+ * Useful for typing Jest mock functions that return partial RPC/API data:
+ * ```ts
+ * const mock = jest.fn() as jest.MockedFunction<DeepPartialReturn<SomeApi["method"]>>;
+ * mock.mockResolvedValue({ onlyTheFieldsWeNeed: true });
+ * ```
+ */
+export type DeepPartialReturn<F extends (...args: never[]) => unknown> = (
+  ...args: Parameters<F>
+) => Promise<DeepPartial<Awaited<ReturnType<F>>>>

package/src/utils.test.ts

@@ -0,0 +1,23 @@
+import BigNumber from 'bignumber.js'
+import { fromBigNumberToBigInt } from './utils'
+
+describe('bigNumberToBigInt', () => {
+  it('should convert BigNumber to BigInt', () => {
+    const bigNumber = new BigNumber('42')
+    const result = fromBigNumberToBigInt(bigNumber)
+    expect(result).toEqual(BigInt('42'))
+  })
+
+  it('should return the default value if input is undefined', () => {
+    const value = undefined
+    const defaultValue = BigInt(12)
+    const result = fromBigNumberToBigInt(value, defaultValue)
+    expect(result).toEqual(defaultValue)
+  })
+  it('should convert to BigInt for very large numbers', () => {
+    const valueStr = '1234567890123456789012345678901234567890'
+    const valBignumber = new BigNumber(valueStr)
+    const valBigint = fromBigNumberToBigInt(valBignumber)
+    expect(valBigint).toEqual(BigInt(valueStr))
+  })
+})

package/src/utils.ts

@@ -0,0 +1,20 @@
+import BigNumber from 'bignumber.js'
+import { SendTransactionIntent, StakingTransactionIntent, TransactionIntent } from './api'
+
+export function fromBigNumberToBigInt<T>(
+  bigNumber: BigNumber | undefined,
+  defaultValue?: T
+): bigint | T {
+  if (bigNumber != null) {
+    return BigInt(bigNumber.toFixed())
+  }
+  return defaultValue as T
+}
+
+export function isSendTransactionIntent(tx: TransactionIntent): tx is SendTransactionIntent {
+  return tx.intentType === 'transaction'
+}
+
+export function isStakingTransactionIntent(tx: TransactionIntent): tx is StakingTransactionIntent {
+  return tx.intentType === 'staking'
+}

package/tsconfig.build.json

@@ -0,0 +1,18 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "customConditions": []
+  },
+  "exclude": [
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "**/*.spec.ts",
+    "**/*.spec.tsx",
+    "**/__tests__/**/*",
+    "**/tests/**/*",
+    "**/*.test.js",
+    "**/*.test.jsx",
+    "**/*.spec.js",
+    "**/*.spec.jsx"
+  ]
+}

package/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "extends": "../tsconfig.base",
+  "compilerOptions": {
+    "declaration": true,
+    "declarationMap": true,
+    "downlevelIteration": true,
+    "lib": [
+      "es2020",
+      "dom"
+    ],
+    "types": [
+      "node",
+      "jest"
+    ],
+    "outDir": "lib",
+    "exactOptionalPropertyTypes": true,
+    "typeRoots": [
+      "./types",
+      "./node_modules/@types"
+    ]
+  },
+  "include": [
+    "src/**/*",
+    "types/*.d.ts"
+  ]
+}