@ canton-network/ core-splice- professor

共享 提供者 与Canton分类账交谈的抽象内容(JSON Ledger) API)或通过钱包/dApp API.

消费者从不自己调用分类账或特定运输工具。 他们使用一个接口:

import {
    AbstractProvider,
    Provider,
} from '@canton-network/core-splice-provider'

形状如下 EIP-1193 (英语) (单位:千美元)request + 活动) 没有Ethereum方法语义学。 具体API在其他地方有定义——例如: CIP-103 (中文(简体) ) 用于 dApps 的 和Canton JSON Ledger API进行直接访问.

发表于 无 下级 阿帕奇2.0 (英语).

安装

npm install @canton-network/core-splice-provider

目标

• 一个接口 直接分类账访问和钱包中介访问
• 迁移不可知性 - HTTP, , (韩语), postMessage, SSE, 进行中, 或者其他任何东西
• 权威不可知论 ——实施选择如何获得证书
• 请求+活动 —— 说 request 用于RPC型呼叫; on 编号 : removeListener 编号 : emit 对流
• 类型方法 - 从方法名称推断出参数和结果
• 小面积 ——易用其他语言再实施;可单独发布交通专用供应商

这个软件包做什么 没有 定义: LAPI 或 dApp 方法是否存在, 如何认证 工作,或钱包/UI行为。 这些是密码和混凝土供应商的.

flowchart TB
    subgraph consumers [Consumers]
        DappSDK["dApp SDK"]
        WalletSDK["Wallet SDK"]
        Custom["Custom app / tooling"]
    end

    Provider["Provider / AbstractProvider<br/><i>request · on · emit · removeListener</i>"]

    subgraph impls [Implementations]
        LedgerP["LedgerProvider"]
        SyncP["DappSyncProvider"]
        AsyncP["DappAsyncProvider"]
    end

    subgraph transports [Transports]
        HTTP["HTTP"]
        PM["postMessage"]
        SSE["HTTPS + SSE"]
    end

    subgraph backends [Backends]
        LAPI["JSON Ledger API"]
        LocalW["Extension / desktop wallet"]
        RemoteW["Remote wallet gateway"]
    end

    DappSDK --> Provider
    WalletSDK --> Provider
    Custom --> Provider

    Provider --> LedgerP
    Provider --> SyncP
    Provider --> AsyncP

    LedgerP --> HTTP --> LAPI
    SyncP --> PM --> LocalW
    AsyncP --> SSE --> RemoteW

提供者接口

import type { RequestArgs, UnknownRpcTypes } from '@canton-network/core-types'

export type EventListener<T> = (...args: T[]) => void

export interface Provider<T extends UnknownRpcTypes> {
    request<M extends keyof T>(args: RequestArgs<T, M>): Promise<T[M]['result']>

    on<E>(event: string, listener: EventListener<E>): Provider<T>
    emit<E>(event: string, ...args: E[]): boolean
    removeListener<E>(
        event: string,
        listenerToRemove: EventListener<E>
    ): Provider<T>
}

接口不假定支持哪些方法、认证工作如何,或 电话是否通过钱包, 只有输入 request 还有一辆公共汽车.

AbstractProvider

执行事件映射( E)on 编号 : emit 编号 : removeListener叶子 request 抽象 :

export abstract class AbstractProvider<
    T extends UnknownRpcTypes,
> implements Provider<T> {
    abstract request<M extends keyof T>(
        args: RequestArgs<T, M>
    ): Promise<T[M]['result']>

    // on / emit / removeListener provided
}

子类接线 request (HTTP JSON LAPI,窗口) postMessage页:1 (原始内容存档于2013-10-12). SSE等.

打字模式

每一次通话都用方法名键入 M。参数来自 C[M]['params'] 和结果 从 C[M]['result']。帮助者生活在 @canton-network/core-types数字 :

type UnknownRpcTypes = {
    [method: string]: {
        params: unknown
        result: unknown
    }
}

type RequestArgs<
    T extends UnknownRpcTypes,
    M extends keyof T,
> = T[M]['params'] extends never
    ? { method: M }
    : { method: M; params: T[M]['params'] }

斑点通常来自 开放RPC (JSON-RPC风格)或 打开API (编者API). 代码 生成 TypeScript 模式; 提供者将其映射到此模式 params 编号 : result 形状.

OpenRPC (dApp API) (英语)

将每种方法映射到参数和结果. 使用 params: never 当一个方法不需要参数时:

type DappClient = {
    prepareExecute: {
        params: PrepareExecuteParams
        result: PrepareExecuteResult
    }
    status: {
        params: never
        result: StatusResult
    }
}

class DappProvider implements Provider<DappClient> {
    async request<M extends keyof DappClient>(
        args: RequestArgs<DappClient, M>
    ): Promise<DappClient[M]['result']> {
        // dispatch via transport…
    }
}

await provider.request({ method: 'status' })
await provider.request({
    method: 'prepareExecute',
    params: {/* PrepareExecuteParams */},
})

OpenAPI( 编辑 API)

编目访问被曝光为一种RPC式的方法, ledgerApi,其参数编码 HTTP 业务(resource, (中文(简体) ), requestMethod选项 body 编号 : path 编号 : query) (中文(简体) ).

就操作类型的安全而言,每个Ledger API操作都是工会的单独成员. TypeScript 缩小参数和结果 resource + 键 requestMethod 你也可以通过一个 明确的操作类型参数 :

type LedgerClient =
    | {
          ledgerApi: {
              params: {
                  resource: '/v2/parties'
                  requestMethod: 'get'
                  query: { /* … */ }
              }
              result: ListKnownPartiesResponse
          }
      }
    | {
          ledgerApi: {
              params: {
                  resource: '/v2/parties'
                  requestMethod: 'post'
                  body: AllocatePartyRequest
              }
              result: AllocatePartyResponse
          }
      }
    | /* … */

股票 OpenAPI 代码源不会释放出此形状; 专用生成器将生成 使用面向提供者的操作类型 @canton-network/core-provider-ledger。 。 。 .

执行情况

高级SDK(@canton-network/dapp-sdk, (中文(简体) ), @canton-network/wallet-sdk坐在这些上 提供商因此应用代码为本地和远程钱包保留了相同的接口.

最小自定义提供者

import { AbstractProvider } from '@canton-network/core-splice-provider'
import { RequestArgs } from '@canton-network/core-types'

type MyRpc = {
    ping: { params: { message: string }; result: string }
}

class MyProvider extends AbstractProvider<MyRpc> {
    async request<M extends keyof MyRpc>(
        args: RequestArgs<MyRpc, M>
    ): Promise<MyRpc[M]['result']> {
        if (args.method === 'ping') {
            return `pong:${args.params.message}` as MyRpc[M]['result']
        }
        throw new Error('Unsupported method')
    }
}

const provider = new MyProvider()
provider.on('ready', () => console.log('ready'))
await provider.request({ method: 'ping', params: { message: 'hi' } })

活动

AbstractProvider 维护内在的收听器地图 :

• on(event, listener) 登记
• removeListener(event, listener) - 未登记
• emit(event, …args) ——通知;返回 false 如果没人听

事件名称和有效载荷来自混凝土API(例如CIP-103) statusChanged, (中文(简体) ), accountsChanged, (中文(简体) ), txChanged,加仅使用自动同步 connected 财务报告和审定财务报表 messageSignature) (中文(简体) ). 这个 软件包只提供订阅机.

错误

执行应披露一致的错误形状(代码+消息),无论 / JSON-RPC故障。 (单位:千美元) 供应商通常遵循EIP-1193 / EIP-1474式代码;见 dApp SDK 错误引用。 。 。 .

出口

RPC 地图助手(UnknownRpcTypes, (中文(简体) ), RequestArgs)为 @canton-network/core-types。 。 。 .

相关软件包