@ledgerhq/types-live 6.22.0

package/src/account.ts

@@ -0,0 +1,295 @@
+import type { BigNumber } from "bignumber.js";
+import type {
+  CryptoCurrency,
+  TokenCurrency,
+  Unit,
+} from "@ledgerhq/types-cryptoassets";
+import type { OperationRaw, Operation } from "./operation";
+import type { DerivationMode } from "./derivation";
+import type { SwapOperation, SwapOperationRaw } from "./swap";
+import type { NFT, NFTRaw } from "./nft";
+
+// This is the old cache and now DEPRECATED (pre v2 portfoli)
+export type GranularityId = "HOUR" | "DAY" | "WEEK";
+
+// the cache is maintained for as many granularity as we need on Live.
+// it's currently an in memory cache so there is no problem regarding the storage.
+// in future, it could be saved and we can rethink how it's stored (independently of how it's in memory)
+export type BalanceHistoryCache = Record<
+  GranularityId,
+  BalanceHistoryDataCache
+>;
+
+// the way BalanceHistoryDataCache works is:
+// - a "cursor" date which is the "latestDate" representing the latest datapoint date. it's null if it never was loaded or if it's empty.
+// - an array of balances. balances are stored in JSNumber even tho internally calculated with bignumbers because we want very good perf. it shouldn't impact imprecision (which happens when we accumulate values, not when presenting to user)
+// there are as much value in that array as there are historical datapoint for a given account.
+// each time an account will sync, it potentially update it by adding a datapoint and possibility updating the cursor in that case.
+export type BalanceHistoryDataCache = {
+  latestDate: number | null | undefined;
+  balances: number[];
+};
+
+/**
+ * A token belongs to an Account and share the parent account address
+ */
+export type TokenAccount = {
+  type: "TokenAccount";
+  id: string;
+  // id of the parent account this token account belongs to
+  parentId: string;
+  token: TokenCurrency;
+  balance: BigNumber;
+  spendableBalance: BigNumber;
+  // in case of compound, this is the associated balance for the associated ctoken
+  compoundBalance?: BigNumber;
+  creationDate: Date;
+  operationsCount: number;
+  operations: Operation[];
+  pendingOperations: Operation[];
+  starred: boolean;
+  // Cache of balance history that allows a performant portfolio calculation.
+  // currently there are no "raw" version of it because no need to at this stage.
+  // could be in future when pagination is needed.
+  balanceHistoryCache: BalanceHistoryCache;
+  // Swap operations linked to this account
+  swapHistory: SwapOperation[];
+  approvals?: Array<{
+    sender: string;
+    value: string;
+  }>;
+};
+
+/**
+ * A child account belongs to an Account but has its own address.
+ */
+export type ChildAccount = {
+  type: "ChildAccount";
+  id: string;
+  name: string;
+  starred: boolean;
+  // id of the parent account this token account belongs to
+  parentId: string;
+  currency: CryptoCurrency;
+  address: string;
+  balance: BigNumber;
+  creationDate: Date;
+  operationsCount: number;
+  operations: Operation[];
+  pendingOperations: Operation[];
+  // Cache of balance history that allows a performant portfolio calculation.
+  // currently there are no "raw" version of it because no need to at this stage.
+  // could be in future when pagination is needed.
+  balanceHistoryCache: BalanceHistoryCache;
+  // Swap operations linked to this account
+  swapHistory: SwapOperation[];
+};
+
+/**
+ *
+ */
+export type Address = {
+  address: string;
+  derivationPath: string;
+};
+
+/**
+ * Account type is the main level account of a blockchain currency.
+ * Each family maybe need an extra field, to solve this, you can have some subtyping like this:
+
+
+    export type BitcoinAccount = Account & { bitcoinResources: BitcoinResources }
+
+and all parts where we would need it, we would need to cast,
+
+    const bitcoinAccount = account as BitcoinAccount;
+
+and that BitcoinAccount type would be part of a coin integration family specific indeed.
+ */
+export type Account = {
+  type: "Account";
+  // unique account identifier
+  id: string;
+  // a unique way to identify a seed the account was associated with
+  // it MUST be different between 2 seeds
+  // but it is not necessarily the same between 2 accounts (if possible – not always possible)
+  // in BTC like accounts, we use pubKey(purpose'/coinType')
+  // For other accounts that don't have sub derivation, we have used the account address
+  seedIdentifier: string;
+  // account xpub if available
+  xpub?: string;
+  // Identify the derivation used. it allows us to map this to a derivation scheme.
+  // example of values: segwit | unsplit | segwit_unsplit | mew | eth_mew (eg for etc accounts on eth)
+  // the special value of '' means it's bip44 with purpose 44.
+  derivationMode: DerivationMode;
+  // the iterated number to derive the account in a given derivationMode config
+  // in context of bip44, it would be the account field of bip44 ( m/purpose'/cointype'/account' )
+  index: number;
+  // next receive address. to be used to display to user.
+  // (deprecated - corresponds to freshAddresses[0].address)
+  freshAddress: string;
+  // The path linked to freshAddress. to be used to validate with the device if it corresponds to freshAddress.
+  // example: 44'/0'/0'/0/0
+  // (deprecated - corresponds to freshAddresses[0].derivationPath)
+  freshAddressPath: string;
+  // an array containing all fresh addresses and paths
+  // may be empty if no sync has occurred
+  freshAddresses: Address[];
+  // account name
+  name: string;
+  // starred
+  starred: boolean;
+  // says if the account essentially "exists". an account has been used in the past, but for some reason the blockchain finds it empty (no ops, no balance,..)
+  used: boolean;
+  // account balance in satoshi
+  balance: BigNumber;
+  // part of the balance that can effectively be spent
+  spendableBalance: BigNumber;
+  // date the account started "existing", essentially the date of the older tx received/done of this account
+  // It is equal to Date.now() for EMPTY accounts because empty account don't really "exists"
+  creationDate: Date;
+  // the last block height currently synchronized
+  blockHeight: number;
+  // ------------------------------------- Specific account fields
+  // currency of this account
+  currency: CryptoCurrency;
+  // user preferred unit to use. unit is coming from currency.units. You can assume currency.units.indexOf(unit) will work. (make sure to preserve reference)
+  unit: Unit;
+  // The total number of operations (operations[] can be partial)
+  operationsCount: number;
+  // lazy list of operations that exists on the blockchain.
+  operations: Operation[];
+  // pending operations that has been broadcasted but are not yet in operations
+  // this is for optimistic updates UI. the Operation objects are temporary and
+  // might not be the real one that will arrives on operations array.
+  // only Operation#id needs to be guaranteed the same.
+  // the array resulting of pendingOperations.concat(operations)
+  // is guaranteed to contains unique ops (by id) at any time and also is time DESC sorted.
+  pendingOperations: Operation[];
+  // used to know when the last sync happened
+  lastSyncDate: Date;
+  // An account can have sub accounts.
+  // A sub account can be either a token account or a child account in some blockchain.
+  // They are attached to the parent account in the related blockchain.
+  // CONVENTION:
+  // a SubAccount is living inside an Account but is not an entity on its own,
+  // therefore, there is no .parentAccount in it, which will means you will need to always have a tuple of (parentAccount, account)
+  // we will use the naming (parentAccount, account) everywhere because a sub account is not enough and you need the full context with this tuple.
+  // These are two valid examples:
+  // I'm inside a ZRX token account of Ethereum 1: { parentAccount: Ethereum 1, account: ZRX }
+  // I'm just inside the Ethereum 1: { account: Ethereum 1, parentAccount: undefined }
+  // "account" is the primary account that you use/select/view. It is a `AccountLike`.
+  // "parentAccount", if available, is the contextual account. It is a `?Account`.
+  subAccounts?: SubAccount[];
+  // Cache of balance history that allows a performant portfolio calculation.
+  // currently there are no "raw" version of it because no need to at this stage.
+  // could be in future when pagination is needed.
+  balanceHistoryCache: BalanceHistoryCache;
+  // Swap operations linked to this account
+  swapHistory: SwapOperation[];
+  // Hash used to discard tx history on sync
+  syncHash?: string;
+  // Array of NFTs computed by diffing NFTOperations ordered from newest to oldest
+  nfts?: NFT[];
+};
+
+/**
+ * super type that is either a token or a child account
+ */
+export type SubAccount = TokenAccount | ChildAccount;
+/**
+ * One of the Account type
+ */
+export type AccountLike = Account | SubAccount;
+/**
+ * an array of AccountLikes
+ */
+export type AccountLikeArray =
+  | AccountLike[]
+  | TokenAccount[]
+  | ChildAccount[]
+  | Account[];
+/**
+ *
+ */
+export type TokenAccountRaw = {
+  type: "TokenAccountRaw";
+  id: string;
+  starred?: boolean;
+  parentId: string;
+  tokenId: string;
+  creationDate?: string;
+  operationsCount?: number;
+  operations: OperationRaw[];
+  pendingOperations: OperationRaw[];
+  balance: string;
+  spendableBalance?: string;
+  compoundBalance?: string;
+  balanceHistoryCache?: BalanceHistoryCache;
+  swapHistory?: SwapOperationRaw[];
+  approvals?: Array<{
+    sender: string;
+    value: string;
+  }>;
+};
+/**
+ *
+ */
+export type ChildAccountRaw = {
+  type: "ChildAccountRaw";
+  id: string;
+  name: string;
+  starred?: boolean;
+  parentId: string;
+  currencyId: string;
+  address: string;
+  creationDate?: string;
+  operationsCount?: number;
+  operations: OperationRaw[];
+  pendingOperations: OperationRaw[];
+  balance: string;
+  balanceHistoryCache?: BalanceHistoryCache;
+  swapHistory?: SwapOperationRaw[];
+};
+/**
+ *
+ */
+export type AccountRaw = {
+  id: string;
+  seedIdentifier: string;
+  xpub?: string;
+  derivationMode: DerivationMode;
+  index: number;
+  freshAddress: string;
+  freshAddressPath: string;
+  freshAddresses: Address[];
+  name: string;
+  starred?: boolean;
+  used?: boolean;
+  balance: string;
+  spendableBalance?: string;
+  blockHeight: number;
+  creationDate?: string;
+  operationsCount?: number;
+  // this is optional for backward compat
+  // ------------------------------------- Specific raw fields
+  currencyId: string;
+  operations: OperationRaw[];
+  pendingOperations: OperationRaw[];
+  unitMagnitude: number;
+  lastSyncDate: string;
+  endpointConfig?: string | null | undefined;
+  subAccounts?: SubAccountRaw[];
+  balanceHistoryCache?: BalanceHistoryCache;
+  swapHistory?: SwapOperationRaw[];
+  syncHash?: string;
+  nfts?: NFTRaw[];
+};
+/**
+ *
+ */
+export type SubAccountRaw = TokenAccountRaw | ChildAccountRaw;
+/**
+ *
+ */
+export type AccountRawLike = AccountRaw | SubAccountRaw;

package/src/bridge.ts

@@ -0,0 +1,149 @@
+// NB this new "bridge" is a re-take of live-desktop bridge ideas
+// with a focus to eventually make it shared across both projects.
+// a WalletBridge is implemented on renderer side.
+// this is an abstraction on top of underlying blockchains api (libcore / ethereumjs / ripple js / ...)
+// that would directly be called from UI needs.
+import { BigNumber } from "bignumber.js";
+import type { Observable } from "rxjs";
+import type { CryptoCurrency } from "@ledgerhq/types-cryptoassets";
+import type { AccountLike, Account, AccountRaw } from "./account";
+import type {
+  TransactionStatus,
+  SignOperationEvent,
+  SignedOperation,
+} from "./transaction";
+import type { Operation } from "./operation";
+import type { DerivationMode } from "./derivation";
+import type { SyncConfig } from "./pagination";
+
+/**
+ *
+ */
+export type ScanAccountEvent = {
+  type: "discovered";
+  account: Account;
+};
+/**
+ * more events will come in the future
+ */
+export type ScanAccountEventRaw = {
+  type: "discovered";
+  account: AccountRaw;
+};
+
+/**
+ * unique identifier of a device. it will depends on the underlying implementation.
+ */
+export type DeviceId = string;
+
+/**
+ *
+ */
+export type PreloadStrategy = Partial<{
+  preloadMaxAge: number;
+}>;
+
+/**
+ *
+ */
+export type BroadcastArg0 = {
+  account: Account;
+  signedOperation: SignedOperation;
+};
+
+/**
+ *
+ */
+export type SignOperationArg0<T> = {
+  account: Account;
+  transaction: T;
+  deviceId: DeviceId;
+};
+
+/**
+ *
+ */
+export type SignOperationFnSignature<T> = (
+  arg0: SignOperationArg0<T>
+) => Observable<SignOperationEvent>;
+export type BroadcastFnSignature = (arg0: BroadcastArg0) => Promise<Operation>;
+
+/**
+ *
+ */
+export interface CurrencyBridge {
+  // Preload data required for the bridges to work. (e.g. tokens, delegators,...)
+  // Assume to call it at every load time but as lazy as possible (if user have such account already AND/OR if user is about to scanAccounts)
+  // returned value is a serializable object
+  // fail if data was not able to load.
+  preload(currency: CryptoCurrency): Promise<Record<string, any>>;
+  // reinject the preloaded data (typically if it was cached)
+  // method need to treat the data object as unsafe and validate all fields / be backward compatible.
+  hydrate(data: unknown, currency: CryptoCurrency): void;
+  // Scan all available accounts with a device
+  scanAccounts(arg0: {
+    currency: CryptoCurrency;
+    deviceId: DeviceId;
+    scheme?: DerivationMode | null | undefined;
+    syncConfig: SyncConfig;
+    preferredNewAccountScheme?: DerivationMode;
+  }): Observable<ScanAccountEvent>;
+  getPreloadStrategy?: (currency: CryptoCurrency) => PreloadStrategy;
+}
+// Abstraction related to an account
+export interface AccountBridge<T> {
+  // synchronizes an account continuously to update with latest blochchains state.
+  // The function emits updater functions each time there are data changes (e.g. blockchains updates)
+  // an update function is just a Account => Account that perform the changes (to avoid race condition issues)
+  // initialAccount parameter is used to point which account is the synchronization on, but it should not be used in the emitted values.
+  // the sync can be stopped at any time using Observable's subscription.unsubscribe()
+  sync(
+    initialAccount: Account,
+    syncConfig: SyncConfig
+  ): Observable<(arg0: Account) => Account>;
+  receive(
+    account: Account,
+    arg1: {
+      verify?: boolean;
+      deviceId: string;
+      subAccountId?: string;
+      freshAddressIndex?: number;
+    }
+  ): Observable<{
+    address: string;
+    path: string;
+  }>;
+  // a Transaction object is created on UI side as a black box to put all temporary information to build the transaction at the end.
+  // There are a bunch of edit and get functions to edit and extract information out ot this black box.
+  // it needs to be a serializable JS object
+  createTransaction(account: Account): T;
+  updateTransaction(t: T, patch: Partial<T>): T;
+  // prepare the remaining missing part of a transaction typically from network (e.g. fees)
+  // and fulfill it in a new transaction object that is returned (async)
+  // It can fails if the the network is down.
+  prepareTransaction(account: Account, transaction: T): Promise<T>;
+  // calculate derived state of the Transaction, useful to display summary / errors / warnings. tells if the transaction is ready.
+  getTransactionStatus(
+    account: Account,
+    transaction: T
+  ): Promise<TransactionStatus>;
+  // heuristic that provides the estimated max amount that can be set to a send.
+  // this is usually the balance minus the fees, but it really depends between coins (reserve, burn, frozen part of the balance,...).
+  // it is a heuristic in that this is not necessarily correct and it can be +-delta (so the info can exceed the spendable or leave some dust).
+  // it's used as informative UI and also used for "dry run" approaches, but it shouldn't be used to determine the final SEND MAX amount.
+  // it returns an amount in the account unit
+  // if a transaction is provided, it can be used to precise the information
+  // if it not provided, you can assume to take the worst-case scenario (like sending all UTXOs to a legacy address has higher fees resulting in a lower max spendable)
+  estimateMaxSpendable(arg0: {
+    account: AccountLike;
+    parentAccount?: Account | null | undefined;
+    transaction?: T | null | undefined;
+  }): Promise<BigNumber>;
+  // finalizing a transaction by signing it with the ledger device
+  // This results of a "signed" event with a signedOperation
+  // than can be locally saved and later broadcasted
+  signOperation: SignOperationFnSignature<T>;
+  // broadcasting a signed transaction to network
+  // returns an optimistic Operation that this transaction is likely to create in the future
+  broadcast: BroadcastFnSignature;
+}

package/src/derivation.ts

@@ -0,0 +1,4 @@
+/**
+ * DerivationMode is a string identifier of a specific derivation scheme in a list defined in live-common derivation.ts
+ */
+export type DerivationMode = string;

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./derivation";
+export * from "./account";
+export * from "./operation";
+export * from "./portfolio";
+export * from "./transaction";
+export * from "./bridge";
+export * from "./pagination";
+export * from "./nft";

package/src/nft.ts

@@ -0,0 +1,53 @@
+import type BigNumber from "bignumber.js";
+
+/**
+ *
+ */
+export type NFTStandards = "ERC721" | "ERC1155";
+
+/**
+ *
+ */
+export type NFT = {
+  // id crafted by live
+  id: string;
+  // id on chain
+  tokenId: string;
+  amount: BigNumber;
+  collection: {
+    // contract address. Careful 1 contract address != 1 collection as some collections are off-chain
+    // So 1 contract address from OpenSea for example can reprensent an infinity of collections
+    contract: string;
+    // Carefull to non spec compliant NFTs (cryptopunks, cryptokitties, ethrock, and others?)
+    standard: NFTStandards | string;
+  };
+};
+
+/**
+ *
+ */
+export type NFTRaw = Omit<NFT, "amount"> & {
+  amount: string;
+};
+
+/**
+ *
+ */
+export type NFTMetadataLinksProviders = "opensea" | "rarible" | "etherscan";
+
+/**
+ *
+ */
+export type NFTMetadataResponse = {
+  status: 200 | 404 | 500;
+  result?: {
+    contract: string;
+    tokenId: string;
+    tokenName: string | null;
+    nftName: string | null;
+    media: string | null;
+    description: string | null;
+    properties: Array<Record<"key" | "value", string>>;
+    links: Record<NFTMetadataLinksProviders, string>;
+  } | null;
+};

package/src/operation.ts

@@ -0,0 +1,130 @@
+import type { BigNumber } from "bignumber.js";
+import { NFTStandards } from "./nft";
+
+/**
+ *
+ */
+export type OperationType =
+  | "IN"
+  | "OUT"
+  | "NONE"
+  | "CREATE"
+  | "REVEAL"
+  // COSMOS
+  | "DELEGATE"
+  | "UNDELEGATE"
+  | "REDELEGATE"
+  | "REWARD"
+  // TRON
+  | "FEES"
+  | "FREEZE"
+  | "UNFREEZE"
+  // POLKADOT
+  | "VOTE"
+  | "REWARD_PAYOUT"
+  | "BOND"
+  | "UNBOND"
+  | "WITHDRAW_UNBONDED"
+  | "SET_CONTROLLER"
+  | "SLASH"
+  | "NOMINATE"
+  | "CHILL"
+  // COMPOUND TYPE OPERATIONS
+  | "SUPPLY"
+  | "REDEEM"
+  | "APPROVE"
+  // ALGORAND
+  | "OPT_IN"
+  | "OPT_OUT"
+  // NFT
+  | "NFT_IN"
+  | "NFT_OUT";
+
+/**
+ *
+ */
+export type Operation = {
+  // unique identifier (usually hash)
+  id: string;
+  // transaction hash
+  hash: string;
+  // the direction of the operation
+  // IN when funds was received (means the related account is in the recipients)
+  // OUT when funds was sent (means the related account is in the senders)
+  // NONE means this is not an operation related to the account but exists because there is likely an internal transaction
+  type: OperationType;
+  // this is the atomic value of the operation. it is always positive (later will be a BigInt)
+  // in "OUT" case, it includes the fees. in "IN" case, it excludes them.
+  value: BigNumber;
+  // fee of the transaction (in satoshi value)
+  fee: BigNumber;
+  // senders & recipients addresses
+  senders: string[];
+  recipients: string[];
+  // if block* are null, the operation is not yet on the blockchain
+  // the height of the block on the blockchain (number)
+  blockHeight: number | null | undefined;
+  // the hash of the block the operation is in
+  blockHash: string | null | undefined;
+  // if available, this is the sequence number of the transaction in blockchains (aka "nonce" in Ethereum)
+  transactionSequenceNumber?: number;
+  // the account id. available for convenient reason
+  accountId: string;
+  // --------------------------------------------- properties related to NFTs
+  // the specification used for the transaction's event
+  standard?: NFTStandards | string;
+  // address of an account/contract that is approved to make the transfer
+  operator?: string;
+  // address of the contract/collection containing an NFT (tokenId)
+  contract?: string;
+  // Id of an NFT inside its collection/contract
+  tokenId?: string;
+  // --------------------------------------------- specific operation raw fields
+  // transaction date
+  date: Date;
+  // Extra crypto specific fields
+  extra: Record<string, any>;
+  // Has the transaction actually failed? (some blockchain like ethereum will have failed tx appearing)
+  hasFailed?: boolean;
+  // in context of accounts that can have tokens, an operation can contains itself operations
+  // these are not in raw at all because they are meant to be rebuilt from the references
+  subOperations?: Operation[];
+  // in context of accounts that have internal transactions that belong to a parent transaction
+  // we have internal operations. Those are not included in the top level operations but can be presented to UI at that same level
+  internalOperations?: Operation[];
+  // Operations related to ERC721 | ERC1155 tokens
+  nftOperations?: Operation[];
+};
+
+/**
+ *
+ */
+export type OperationRaw = {
+  id: string;
+  hash: string;
+  type: OperationType;
+  value: string;
+  fee: string;
+  senders: string[];
+  recipients: string[];
+  blockHeight: number | null | undefined;
+  blockHash: string | null | undefined;
+  transactionSequenceNumber?: number;
+  accountId: string;
+  hasFailed?: boolean;
+  // --------------------------------------------- properties related to NFTs
+  standard?: NFTStandards | string;
+  operator?: string;
+  contract?: string;
+  tokenId?: string;
+  // --------------------------------------------- specific operation raw fields
+  date: string;
+  extra: Record<string, any>;
+  // would be a serializable version of the extra
+  subOperations?: OperationRaw[];
+  // in context of accounts that have internal transactions that belong to a parent transaction
+  // we have internal operations. Those are not included in the top level operations but can be presented to UI at that same level
+  internalOperations?: OperationRaw[];
+  // Operations related to ERC721 | ERC1155 tokens
+  nftOperations?: OperationRaw[];
+};

package/src/pagination.ts

@@ -0,0 +1,21 @@
+/**
+ * A pagination config holds the user's pagination state
+ * this is a state that usually should leave during the app lifecycle, but is not persisted
+ * it drives the number of operations to poll in accounts
+ * when a user paginate more, the number should accordingly be incremented
+ * The UI should manage scrolling ahead of time (e.g. if 30 ops is displayed and UI have pages of 20 ops, the UI can already request to poll 70 ops so it have 2 pages in advance)
+ * The UI must always do max() to keep the increasing the counter and not going back to lower value: that optim the sync to not recompute things too much
+ */
+export type PaginationConfig = {
+  // operations to pull for each account
+  operationsPerAccountId?: Record<string, number>;
+  // if define and there is no specific account in operationsPerAccountId,
+  // this will be the operations count used
+  operations?: number;
+};
+export type SyncConfig = {
+  paginationConfig: PaginationConfig;
+  // allows to disable the synchronization part – typically to only paginate more
+  withoutSynchronize?: boolean;
+  blacklistedTokenIds?: string[];
+};