@aeternity/aepp-sdk 10.0.0 → 12.0.0

package/src/AeSdkAepp.ts

@@ -0,0 +1,167 @@
+import AeSdkBase, { Account } from './AeSdkBase'
+import AccountBase from './account/Base'
+import AccountRpc from './account/Rpc'
+import { decode, EncodedData } from './utils/encoder'
+import { Accounts, RPC_VERSION, WalletInfo, Network, WalletApi, AeppApi } from './aepp-wallet-communication/rpc/types'
+import RpcClient from './aepp-wallet-communication/rpc/RpcClient'
+import { METHODS, SUBSCRIPTION_TYPES } from './aepp-wallet-communication/schema'
+import {
+  AlreadyConnectedError,
+  NoWalletConnectedError,
+  UnsubscribedAccountError,
+  UnAuthorizedAccountError,
+  RpcConnectionError
+} from './utils/errors'
+import Node from './Node'
+import BrowserConnection from './aepp-wallet-communication/connection/Browser'
+
+/**
+ * RPC handler for AEPP side
+ * Contain functionality for wallet interaction and connect it to sdk
+ */
+export default class AeSdkAepp extends AeSdkBase {
+  name: string
+  onAddressChange: (a: Accounts) => void
+  onDisconnect: (p: any) => void
+  onNetworkChange: (a: Network) => void
+  rpcClient?: RpcClient<WalletApi, AeppApi>
+  _accounts?: Accounts
+
+  /**
+   * @param options - Options
+   * @param options.name - Aepp name
+   * @param options.onAddressChange - Call-back function for update address event
+   * @param options.onDisconnect - Call-back function for disconnect event
+   * @param options.onNetworkChange - Call-back function for update network event
+   */
+  constructor ({
+    name,
+    onAddressChange = () => {},
+    onDisconnect = () => {},
+    onNetworkChange = () => {},
+    ...other
+  }: {
+    name: string
+    onAddressChange: (a: Accounts) => void
+    onDisconnect: (p: any) => void
+    onNetworkChange: (a: Network) => void
+  } & ConstructorParameters<typeof AeSdkBase>[0]) {
+    super(other)
+    this.onAddressChange = onAddressChange
+    this.onDisconnect = onDisconnect
+    this.onNetworkChange = onNetworkChange
+    this.name = name
+  }
+
+  _resolveAccount (account: Account = this.addresses()[0]): AccountBase {
+    if (typeof account === 'string') {
+      const address = account as EncodedData<'ak'>
+      decode(address)
+      if (!this.addresses().includes(address)) throw new UnAuthorizedAccountError(address)
+      account = new AccountRpc({ rpcClient: this.rpcClient, address })
+    }
+    if (account == null) this._ensureAccountAccess()
+    return super._resolveAccount(account)
+  }
+
+  addresses (): Array<EncodedData<'ak'>> {
+    if (this._accounts == null) return []
+    const current = Object.keys(this._accounts.current)[0]
+    return [
+      ...current != null ? [current] : [], ...Object.keys(this._accounts.connected)
+    ] as Array<EncodedData<'ak'>>
+  }
+
+  /**
+   * Connect to wallet
+   * @param connection - Wallet connection object
+   * @param options - Options
+   * @param options.connectNode - Request wallet to bind node
+   * @param options.name - Node name
+   * @param options.select - Select this node as current
+   */
+  async connectToWallet (
+    connection: BrowserConnection,
+    { connectNode = false, name = 'wallet-node', select = false }:
+    { connectNode?: boolean, name?: string, select?: boolean } = {}
+  ): Promise<WalletInfo> {
+    if (this.rpcClient != null) throw new AlreadyConnectedError('You are already connected to wallet')
+    let disconnectParams: any
+    const client = new RpcClient<WalletApi, AeppApi>(
+      connection,
+      () => {
+        delete this.rpcClient
+        delete this._accounts
+        this.onDisconnect(disconnectParams)
+      }, {
+        [METHODS.updateAddress]: (params) => {
+          this._accounts = params
+          this.onAddressChange(params)
+        },
+        [METHODS.updateNetwork]: (params) => {
+          const { node } = params
+          if (node != null) this.addNode(node.name, new Node(node.url), true)
+          this.onNetworkChange(params)
+        },
+        [METHODS.closeConnection]: (params) => {
+          disconnectParams = params
+          client.connection.disconnect()
+        },
+        [METHODS.readyToConnect]: () => {}
+      }
+    )
+    const { node, ...walletInfo } = await client.request(
+      METHODS.connect, { name: this.name, version: RPC_VERSION, connectNode }
+    )
+    if (connectNode) {
+      if (node == null) throw new RpcConnectionError('Missing URLs of the Node')
+      this.addNode(name, new Node(node.url), select)
+    }
+    this.rpcClient = client
+    return walletInfo
+  }
+
+  /**
+   * Disconnect from wallet
+   */
+  disconnectWallet (): void {
+    this._ensureConnected()
+    this.rpcClient.notify(METHODS.closeConnection, { reason: 'bye' })
+    this.rpcClient.connection.disconnect()
+  }
+
+  /**
+   * Ask addresses from wallet
+   * @returns Addresses from wallet
+   */
+  async askAddresses (): Promise<Array<EncodedData<'ak'>>> {
+    this._ensureAccountAccess()
+    return await this.rpcClient.request(METHODS.address, undefined)
+  }
+
+  /**
+   * Subscribe for addresses from wallet
+   * @param type - Subscription type
+   * @param value - Should be one of 'current' (the selected account), 'connected' (all)
+   * @returns Accounts from wallet
+   */
+  async subscribeAddress (
+    type: SUBSCRIPTION_TYPES, value: 'current' | 'connected'
+  ): Promise<ReturnType<WalletApi[METHODS.subscribeAddress]>> {
+    this._ensureConnected()
+    const result = await this.rpcClient.request(METHODS.subscribeAddress, { type, value })
+    this._accounts = result.address
+    return result
+  }
+
+  _ensureConnected (): asserts this is AeSdkAepp & { rpcClient: NonNullable<AeSdkAepp['rpcClient']> } {
+    if (this.rpcClient != null) return
+    throw new NoWalletConnectedError('You are not connected to Wallet')
+  }
+
+  _ensureAccountAccess (): asserts this is AeSdkAepp & { rpcClient: NonNullable<AeSdkAepp['rpcClient']> } {
+    this._ensureConnected()
+    if (this.addresses().length !== 0) return
+    throw new UnsubscribedAccountError()
+  }
+}

package/src/AeSdkBase.ts

@@ -0,0 +1,320 @@
+import * as chainMethods from './chain'
+import * as txMethods from './tx'
+import * as aensMethods from './aens'
+import * as spendMethods from './spend'
+import * as oracleMethods from './oracle'
+import * as contractMethods from './contract/methods'
+import * as contractGaMethods from './contract/ga'
+import { _buildTx } from './tx'
+import { mapObject } from './utils/other'
+import Node, { getNetworkId } from './Node'
+import { AE_AMOUNT_FORMATS } from './utils/amount-formatter'
+import { AMOUNT, TX_TYPE } from './tx/builder/schema'
+import MemoryAccount, { Keypair } from './account/Memory'
+import AccountBase, { isAccountBase } from './account/Base'
+import {
+  CompilerError,
+  DuplicateNodeError,
+  NodeNotFoundError,
+  NotImplementedError,
+  TypeError
+} from './utils/errors'
+import { EncodedData } from './utils/encoder'
+import Compiler from './contract/Compiler'
+
+export type Account = Keypair | AccountBase | any
+
+type NodeInfo = Awaited<ReturnType<Node['getNodeInfo']>> & { name: string }
+
+function getValueOrErrorProxy<Value extends object> (valueCb: () => Value): Value {
+  try {
+    return valueCb()
+  } catch (error) {
+    return new Proxy(
+      {},
+      Object.fromEntries(['get', 'set', 'has'].map(name => [name, () => { throw error }]))
+    ) as Value
+  }
+}
+
+/**
+ * Basic AeSdk class
+ *
+ * AeSdkBase objects are the composition of:
+ * - chain methods
+ * - tx methods
+ * - aens methods
+ * - spend methods
+ * - oracle methods
+ * - contract methods
+ * - contract ga methods
+ * Only by providing the joint functionality of them, most more advanced
+ * operations, i.e. the ones with actual use value on the chain, become
+ * available.
+ */
+class AeSdkBase {
+  _options: {
+    denomination: AE_AMOUNT_FORMATS
+    amount: number
+    [key: string]: any
+  } = { denomination: AE_AMOUNT_FORMATS.AETTOS, amount: AMOUNT }
+
+  pool: Map<string, Node> = new Map()
+  selectedNodeName?: string
+  compilerApi: Compiler
+
+  /**
+   * @param options - Options
+   * @param options.nodes - Array of nodes
+   * @param options.compilerUrl - Url for compiler API
+   * @param options.ignoreVersion - Don't check node or compiler version
+   */
+  constructor (
+    { nodes = [], compilerUrl, ignoreVersion = false, ...options }:
+    {
+      nodes?: Array<{ name: string, instance: Node }>
+      compilerUrl?: string
+      ignoreVersion?: boolean
+      [key: string]: any // TODO: consider combining all possible options instead
+    } = {}
+  ) {
+    Object.assign(this._options, options)
+
+    nodes.forEach(({ name, instance }, i) => this.addNode(name, instance, i === 0))
+
+    if (compilerUrl == null) {
+      this.compilerApi = getValueOrErrorProxy(() => {
+        throw new CompilerError('You can\'t use Compiler API. Compiler is not ready!')
+      })
+    } else this.setCompilerUrl(compilerUrl, { ignoreVersion })
+  }
+
+  setCompilerUrl (
+    compilerUrl: string, { ignoreVersion = false }: { ignoreVersion?: boolean } = {}
+  ): void {
+    this.compilerApi = new Compiler(compilerUrl, { ignoreVersion })
+  }
+
+  get api (): Node {
+    this.ensureNodeConnected()
+    return this.pool.get(this.selectedNodeName) as Node
+  }
+
+  /**
+   * Add Node
+   * @param name - Node name
+   * @param node - Node instance
+   * @param select - Select this node as current
+   * @example
+   * ```js
+   * // add and select new node with name 'testNode'
+   * aeSdkBase.addNode('testNode', new Node({ url }), true)
+   * ```
+   */
+  addNode (name: string, node: Node, select = false): void {
+    if (this.pool.has(name)) throw new DuplicateNodeError(name)
+
+    this.pool.set(name, node)
+    if (select || this.selectedNodeName == null) {
+      this.selectNode(name)
+    }
+  }
+
+  /**
+   * Select Node
+   * @param name - Node name
+   * @example
+   * nodePool.selectNode('testNode')
+   */
+  selectNode (name: string): void {
+    if (!this.pool.has(name)) throw new NodeNotFoundError(`Node with name ${name} not in pool`)
+    this.selectedNodeName = name
+  }
+
+  /**
+   * Get NetworkId of current Node
+   * @example
+   * nodePool.getNetworkId()
+   */
+  readonly getNetworkId = getNetworkId
+
+  /**
+   * Check if you have selected node
+   * @example
+   * nodePool.isNodeConnected()
+   */
+  isNodeConnected (): this is AeSdkBase & { selectedNodeName: string } {
+    return this.selectedNodeName != null
+  }
+
+  protected ensureNodeConnected (): asserts this is AeSdkBase & { selectedNodeName: string } {
+    if (!this.isNodeConnected()) {
+      throw new NodeNotFoundError('You can\'t use Node API. Node is not connected or not defined!')
+    }
+  }
+
+  /**
+   * Get information about node
+   * @example
+   * ```js
+   * nodePool.getNodeInfo() // { name, version, networkId, protocol, ... }
+   * ```
+   */
+  async getNodeInfo (): Promise<NodeInfo> {
+    this.ensureNodeConnected()
+    return {
+      name: this.selectedNodeName,
+      ...await this.api.getNodeInfo()
+    }
+  }
+
+  /**
+   * Get array of available nodes
+   * @example
+   * nodePool.getNodesInPool()
+   */
+  async getNodesInPool (): Promise<NodeInfo[]> {
+    return await Promise.all(
+      Array.from(this.pool.entries()).map(async ([name, node]) => ({
+        name,
+        ...await node.getNodeInfo()
+      }))
+    )
+  }
+
+  addresses (): Array<EncodedData<'ak'>> {
+    return []
+  }
+
+  async address ({ onAccount }: { onAccount?: Account } = {}): Promise<EncodedData<'ak'>> {
+    return await this._resolveAccount(onAccount).address()
+  }
+
+  async sign (
+    data: string | Uint8Array, { onAccount, ...options }: { onAccount?: Account } = {}
+  ): Promise<Uint8Array> {
+    return await this._resolveAccount(onAccount).sign(data, options)
+  }
+
+  async signTransaction (
+    tx: EncodedData<'tx'>,
+    { onAccount, ...options }: { onAccount?: Account } & Parameters<AccountBase['signTransaction']>[1] = {}
+  ): Promise<EncodedData<'tx'>> {
+    return await this._resolveAccount(onAccount)
+      .signTransaction(tx, { ...options, networkId: await this.getNetworkId(options) })
+  }
+
+  async signMessage (
+    message: string,
+    { onAccount, ...options }: { onAccount?: Account } & Parameters<AccountBase['signMessage']>[1] = {}
+  ): Promise<string | Uint8Array> {
+    return await this._resolveAccount(onAccount).signMessage(message, options)
+  }
+
+  async verifyMessage (
+    message: string,
+    signature: string | Uint8Array,
+    { onAccount, ...options }: { onAccount?: Account } & Parameters<AccountBase['verifyMessage']>[2] = {}
+  ): Promise<boolean> {
+    return await this._resolveAccount(onAccount).verifyMessage(message, signature, options)
+  }
+
+  /**
+   * Resolves an account
+   * @param account - ak-address, instance of AccountBase, or keypair
+   */
+  _resolveAccount (account?: Account): AccountBase {
+    switch (account !== null && typeof account) {
+      case 'string':
+        throw new NotImplementedError('Address in AccountResolver')
+      case 'object':
+        return isAccountBase(account) ? account : new MemoryAccount({ keypair: account })
+      default:
+        throw new TypeError(
+          'Account should be an address (ak-prefixed string), ' +
+          `keypair, or instance of AccountBase, got ${String(account)} instead`)
+    }
+  }
+
+  async _getOptions (
+  ): Promise<{ onNode: Node, onAccount: AccountBase, onCompiler: Compiler, networkId: string }> {
+    return {
+      ...this._options,
+      onNode: getValueOrErrorProxy(() => this.api),
+      onAccount: getValueOrErrorProxy(() => this._resolveAccount()),
+      onCompiler: getValueOrErrorProxy(() => this.compilerApi),
+      // TODO: remove networkId
+      networkId: (await this.api?.getStatus()).networkId
+    }
+  }
+
+  async buildTx<TxType extends TX_TYPE> (
+    txType: TxType,
+    options: Omit<Parameters<typeof _buildTx<TxType>>[1], 'onNode'> & { onNode?: Node }
+  ): Promise<EncodedData<'tx'>> {
+    // @ts-expect-error
+    return await _buildTx<TxType>(txType, {
+      ...await this._getOptions(),
+      ...options
+    })
+  }
+}
+
+const { _buildTx: _, ...txMethodsOther } = txMethods
+
+const methods = {
+  ...chainMethods,
+  ...txMethodsOther,
+  ...aensMethods,
+  ...spendMethods,
+  ...oracleMethods,
+  ...contractMethods,
+  ...contractGaMethods
+} as const
+
+type RequiredKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? never : K
+}[keyof T]
+
+type OptionalIfNotRequired<T extends [any]> = RequiredKeys<T[0]> extends never ? T | [] : T
+
+type MakeOptional<Args extends any[]> = Args extends [infer Head, ...infer Tail]
+  ? Tail extends []
+    ? Head extends object
+      ? OptionalIfNotRequired<[Omit<Head, 'onNode' | 'onCompiler' | 'onAccount'>
+      & { onNode?: Node, onCompiler?: Compiler, onAccount?: AccountBase | EncodedData<'ak'> | Keypair }]>
+      : [Head]
+    : [Head, ...MakeOptional<Tail>]
+  : never
+
+type TransformMethods <Methods extends { [key: string]: Function }> =
+  {
+    [Name in keyof Methods]:
+    Methods[Name] extends (...args: infer Args) => infer Ret
+      ? (...args: MakeOptional<Args>) => Ret
+      : never
+  }
+
+interface AeSdkBaseMethods extends TransformMethods<typeof methods> {}
+
+Object.assign(AeSdkBase.prototype, mapObject<Function, Function>(
+  methods,
+  ([name, handler]) => [
+    name,
+    async function (...args: any[]) {
+      const instanceOptions = await this._getOptions()
+      const lastArg = args[args.length - 1]
+      if (lastArg != null && typeof lastArg === 'object' && lastArg.constructor === Object) {
+        Object.assign(lastArg, {
+          ...instanceOptions,
+          ...lastArg,
+          ...lastArg.onAccount != null && { onAccount: this._resolveAccount(lastArg.onAccount) }
+        })
+      } else args.push(instanceOptions)
+      return handler(...args)
+    }
+  ]
+))
+
+export default AeSdkBase as new (options: ConstructorParameters<typeof AeSdkBase>[0]) =>
+AeSdkBase & AeSdkBaseMethods