From 8dca51e8dd91757734bd6a448fc9afe1aa670e90 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C4=B1z=C4=B1r=20Sefa=20=C4=B0rken?= Date: Mon, 22 Jul 2024 14:04:02 +0300 Subject: [PATCH 1/7] docs: add AsyncAPI definition --- docs/CIP/CIP-XXXX/src/cardano-service.yml | 428 ++++++++++++++++++++++ 1 file changed, 428 insertions(+) create mode 100644 docs/CIP/CIP-XXXX/src/cardano-service.yml diff --git a/docs/CIP/CIP-XXXX/src/cardano-service.yml b/docs/CIP/CIP-XXXX/src/cardano-service.yml new file mode 100644 index 0000000..c07a595 --- /dev/null +++ b/docs/CIP/CIP-XXXX/src/cardano-service.yml @@ -0,0 +1,428 @@ +asyncapi: 3.0.0 +info: + title: Wallet API + version: 1.0.0 + description: >- + The primary goal of a well-designed API for a multi-chain digital wallet is + to provide the data required to construct transactions and to allow deriving + the current state of the wallet while the set of subscribed blockchains is + continuously extended. This includes aggregating transactions and on-chain + events to present users their transaction history, current balance, as well + as chain-specific features such as stake delegation or staking rewards. + + + The proposed API design offers different endpoints to retrieve the same data + in order to support a wide range of edge clients, in particular clients with + an intermittent connection or that are bandwidth-constrained. + license: + name: Apache 2.0 + url: 'https://www.apache.org/licenses/LICENSE-2.0' +defaultContentType: application/json +servers: + cardano-mainnet: + host: mainnet.lacev2.com + protocol: wss + description: Cardano Mainnet API + tags: + - name: 'env:cardano-mainnet' + description: This environment is for Cardano mainnet production + - name: 'visibility:public' + description: This resource is public to all users + cardano-preprod: + host: preprod.lacev2.com + protocol: wss + description: Cardano Preprod API + tags: + - name: 'env:cardano-mainnet' + description: This environment is for Cardano preprod + - name: 'visibility:public' + description: This resource is public to all users +channels: + cardano: + address: /v1/wallet + messages: + welcome: + $ref: '#/components/messages/welcome' + genesis: + $ref: '#/components/messages/genesis' + transaction: + $ref: '#/components/messages/transaction' + protocolParameters: + $ref: '#/components/messages/protocolParameters' + eraSummary: + $ref: '#/components/messages/eraSummary' + subscribe: + $ref: '#/components/messages/subscribe' +operations: + doSubscribe: + summary: A client subscription + description: >- + Sent by client to server right after establishing a connection. New + clients must authenticate themselves when subscribing to any blockchain + events via a signature. + action: send + messages: + - $ref: '#/channels/cardano/messages/subscribe' + channel: + $ref: '#/channels/cardano' + onConnect: + summary: On client connection + description: Event received when a client connects to the server + action: receive + messages: + - $ref: '#/channels/cardano/messages/welcome' + channel: + $ref: '#/channels/cardano' + onGenesis: + summary: On client connection + description: Event received if the client is syncing from the origin + action: receive + messages: + - $ref: '#/channels/cardano/messages/genesis' + channel: + $ref: '#/channels/cardano' + onTransaction: + summary: On a relevant transaction event + description: Event received if there is a relevant transaction for the client + action: receive + messages: + - $ref: '#/channels/cardano/messages/transaction' + channel: + $ref: '#/channels/cardano' + onEpochBoundary: + summary: On epoch boundry + description: Event receieved on every epoch boundary transition + action: receive + messages: + - $ref: '#/channels/cardano/messages/protocolParameters' + channel: + $ref: '#/channels/cardano' + onEraTransition: + summary: On era transtitions + description: Event receieved on era transitions for updated slot length + action: receive + messages: + - $ref: '#/channels/cardano/messages/eraSummary' + channel: + $ref: '#/channels/cardano' +components: + messages: + welcome: + name: Welcome + title: Welcome message + summary: >- + This message is sent to all clients as the first message immediately + upon establishing a connection. It contains essential details about + the server and API, helping clients understand the environment they are + interacting with. + contentType: application/json + genesis: + name: Genesis + title: Genesis message + summary: >- + This top level message key is added by the server as part of any + synchronization process that starts from the genesis point, also + sometimes referred to origin. + contentType: application/json + payload: + $ref: '#/components/schemas/genesisPayload' + transaction: + name: Transaction + title: Transaction message + summary: >- + The server broadcasts new, relevant transaction data to connected + clients using chain-specific encoding protocols. This approach closely + mimics the native blockchain synchronization process, ensuring + compatibility and efficiency. By adhering to each blockchain's native + encoding, the system maintains consistency with existing communication + protocols. + contentType: application/json + payload: + $ref: '#/components/schemas/transactionPayload' + protocolParameters: + name: protocolParameters + title: Protocol Parameters Server Message Partial + summary: >- + This top level message key is added by the server as part of any + synchronization process for every epoch boundary transition. + contentType: application/json + payload: + $ref: '#/components/schemas/protocolParameterPayload' + tip: + name: Tip + title: Server Tip Message Partial + summary: >- + This message partial is added to all server-sent messages and represents + the latest current tip of the chain. + payload: + $ref: '#/components/schemas/protocolParameterPayload' + eraSummary: + name: Era Summary + title: Era Summary Server Message Partial + summary: >- + Part of any synchronization process for every era transition. It has + similarities with hardfork events on other blockchains but has been + represented by its own message partial. The primary reason a wallet + needs to be aware of era transitions in Cardano is due to potential + network changes. Specifically, since the beginning of Cardano's Shelley + era, the Ouroboros consensus protocol was introduced, which defined a + slot length—a specific duration of time during which a block can be + produced by a leader (stake pool). Initially, this slot length was set + to one second but may change in the future. Therefore, depending on the + slot length, the conversion of a specific point in on-chain time may + vary. In order to show and submit transaction times correctly, wallets + need to know each era's slot length. + subscribe: + name: Subscribe + title: Subscribe message + summary: >- + A message containing client's interests and preferences. New clients + must authenticate themselves when subscribing to any blockchain events + via a signature. + contentType: application/json + payload: + $ref: '#/components/schemas/subscribePayload' + schemas: + welcomePayload: + type: object + properties: + blockchains: + type: array + items: + type: object + dditionalProperties: false + properties: + name: + type: string + genesisPayload: + type: object + properties: + activeSlotsCoefficient: + type: number + format: float + updateQuorum: + type: integer + maxLovelaceSupply: + type: string + networkMagic: + type: integer + epochLength: + type: integer + systemStart: + type: integer + slotsPerKesPeriod: + type: integer + slotLength: + type: integer + maxKesEvolutions: + type: integer + securityParam: + type: integer + transactionPayload: + type: object + properties: + outputIndex: + type: number + txHash: + type: string + transactions: + type: array + format: string + resolvedInputs: + type: array + format: string + point: + type: string + chain: + type: string + tip: + type: string + pointPayload: + type: object + properties: + slot: + type: integer + hash: + type: string + tipPayload: + type: object + properties: + point: + $ref: '#/components/schemas/pointPayload' + protocolParameterPayload: + type: object + properties: + epoch: + type: integer + minFeeA: + type: integer + minFeeB: + type: integer + maxBlockSize: + type: integer + maxTxSize: + type: integer + maxBlockHeaderSize: + type: integer + keyDeposit: + type: string + poolDeposit: + type: string + eMax: + type: integer + nOpt: + type: integer + a0: + type: number + rho: + type: number + tau: + type: number + decentralisationParam: + type: number + extraEntropy: + type: + - 'null' + - string + protocolMajorVer: + type: integer + protocolMinorVer: + type: integer + minUtxo: + type: string + minPoolCost: + type: string + nonce: + type: string + costModels: + type: object + properties: + plutusV1: + type: object + plutusV2: + type: object + priceMem: + type: number + priceStep: + type: number + maxTxExMem: + type: string + maxTxExSteps: + type: string + maxBlockExMem: + type: string + maxBlockExSteps: + type: string + maxValSize: + type: string + collateralPercent: + type: integer + maxCollateralInputs: + type: integer + coinsPerUtxoSize: + type: string + eraSummaryPayload: + type: object + properties: + parameters: + type: object + properties: + epochLength: + type: integer + slotLength: + type: integer + description: Milliseconds + start: + type: object + properties: + slot: + type: integer + time: + type: string + format: date-time + subscribePayload: + type: object + properties: + type: + type: string + enum: + - subscribe + topic: + type: array + items: + type: object + properties: + blockchain: + type: object + properties: + name: + type: string + network: + type: string + publicKey: + type: string + pattern: '^[A-Za-z0-9+/=]*$' + signature: + type: string + pattern: '^[A-Za-z0-9+/=]*$' + cardano: + type: object + properties: + credentials: + type: object + properties: + payment: + type: array + items: + type: string + pattern: '^[A-Za-z0-9+/=]*$' + stake: + type: array + items: + type: string + pattern: '^[A-Za-z0-9+/=]*$' + points: + type: array + properties: + slot: + type: integer + minimum: 0 + hash: + type: string + pattern: '^[A-Za-z0-9+/=]*$' + required: + - slot + - hash + extensions: + type: array + items: + type: object + properties: + name: + type: string + config: + type: object + version: + type: string + required: + - name + - config + - version + required: + - credentials + - extensions + - points + required: + - blockchain + - signature + timestamp: + type: string + format: date-time + required: + - type + - topic + - timestamp + sentAt: + type: string + format: date-time + description: Date and time when the message was sent. From c2da8d4425286f0ebbff0b23536f5f23fdadfff4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C4=B1z=C4=B1r=20Sefa=20=C4=B0rken?= Date: Tue, 23 Jul 2024 12:08:59 +0300 Subject: [PATCH 2/7] docs: mark required fields as required --- docs/CIP/CIP-XXXX/src/cardano-service.yml | 109 ++++++++++++++++++++-- 1 file changed, 102 insertions(+), 7 deletions(-) diff --git a/docs/CIP/CIP-XXXX/src/cardano-service.yml b/docs/CIP/CIP-XXXX/src/cardano-service.yml index c07a595..f1093d2 100644 --- a/docs/CIP/CIP-XXXX/src/cardano-service.yml +++ b/docs/CIP/CIP-XXXX/src/cardano-service.yml @@ -190,10 +190,41 @@ components: type: array items: type: object - dditionalProperties: false properties: name: type: string + network: + type: string + extensions: + type: array + items: + type: object + properties: + name: + type: string + config: {} + default: {} + switchable: + type: boolean + versions: + type: array + items: + type: string + required: + - name + - config + - default + - switchable + - versions + version: + type: string + required: + - name + - network + - extensions + - version + required: + - blockchains genesisPayload: type: object properties: @@ -218,6 +249,17 @@ components: type: integer securityParam: type: integer + required: + - activeSlotsCoefficient + - updateQuorum + - maxLovelaceSupply + - networkMagic + - epochLength + - systemStart + - slotsPerKesPeriod + - slotLength + - maxKesEvolutions + - securityParam transactionPayload: type: object properties: @@ -244,11 +286,17 @@ components: type: integer hash: type: string + height: + type: string + required: + - hash tipPayload: type: object properties: point: $ref: '#/components/schemas/pointPayload' + required: + - point protocolParameterPayload: type: object properties: @@ -321,6 +369,38 @@ components: type: integer coinsPerUtxoSize: type: string + required: + - epoch + - minFeeA + - minFeeB + - maxBlockSize + - maxTxSize + - maxBlockHeaderSize + - keyDeposit + - poolDeposit + - eMax + - nOpt + - a0 + - rho + - tau + - decentralisationParam + - extraEntropy + - protocolMajorVer + - protocolMinorVer + - minUtxo + - minPoolCost + - nonce + - costModels + - priceMem + - priceStep + - maxTxExMem + - maxTxExSteps + - maxBlockExMem + - maxBlockExSteps + - maxValSize + - collateralPercent + - maxCollateralInputs + - coinsPerUtxoSize eraSummaryPayload: type: object properties: @@ -329,17 +409,26 @@ components: properties: epochLength: type: integer - slotLength: - type: integer - description: Milliseconds + slotLength: + type: integer + description: Milliseconds + required: + - epochLength + - slotLength start: type: object properties: slot: type: integer - time: - type: string - format: date-time + time: + type: string + format: date-time + required: + - slot + - time + required: + - parameters + - start subscribePayload: type: object properties: @@ -359,6 +448,9 @@ components: type: string network: type: string + required: + - name + - network publicKey: type: string pattern: '^[A-Za-z0-9+/=]*$' @@ -381,6 +473,9 @@ components: items: type: string pattern: '^[A-Za-z0-9+/=]*$' + required: + - payment + - stake points: type: array properties: From a42d81a28881c1ccb2df8c9007a51f42d2716415 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C4=B1z=C4=B1r=20Sefa=20=C4=B0rken?= Date: Tue, 23 Jul 2024 12:53:02 +0300 Subject: [PATCH 3/7] docs: reference point object in asyncapi --- docs/CIP/CIP-XXXX/src/cardano-service.yml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/CIP/CIP-XXXX/src/cardano-service.yml b/docs/CIP/CIP-XXXX/src/cardano-service.yml index f1093d2..88ae162 100644 --- a/docs/CIP/CIP-XXXX/src/cardano-service.yml +++ b/docs/CIP/CIP-XXXX/src/cardano-service.yml @@ -274,11 +274,13 @@ components: type: array format: string point: - type: string + type: object + $ref: '#/components/schemas/pointPayload' chain: type: string tip: - type: string + type: object + $ref: '#/components/schemas/pointPayload' pointPayload: type: object properties: @@ -478,6 +480,9 @@ components: - stake points: type: array + items: + type: object + $ref: '#/components/schemas/pointPayload' properties: slot: type: integer From f0972a04724e78c0fe568885ec7eb4b83462b55c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C4=B1z=C4=B1r=20Sefa=20=C4=B0rken?= Date: Tue, 23 Jul 2024 13:39:52 +0300 Subject: [PATCH 4/7] docs: change server urls to localhost --- docs/CIP/CIP-XXXX/src/cardano-service.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/CIP/CIP-XXXX/src/cardano-service.yml b/docs/CIP/CIP-XXXX/src/cardano-service.yml index 88ae162..6465983 100644 --- a/docs/CIP/CIP-XXXX/src/cardano-service.yml +++ b/docs/CIP/CIP-XXXX/src/cardano-service.yml @@ -20,7 +20,7 @@ info: defaultContentType: application/json servers: cardano-mainnet: - host: mainnet.lacev2.com + host: 'localhost:8080' protocol: wss description: Cardano Mainnet API tags: @@ -29,11 +29,11 @@ servers: - name: 'visibility:public' description: This resource is public to all users cardano-preprod: - host: preprod.lacev2.com + host: 'localhost:8080' protocol: wss description: Cardano Preprod API tags: - - name: 'env:cardano-mainnet' + - name: 'env:cardano-preprod' description: This environment is for Cardano preprod - name: 'visibility:public' description: This resource is public to all users From c44b90a05d8ba855debd6baaf644ffefad4d481e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C4=B1z=C4=B1r=20Sefa=20=C4=B0rken?= Date: Tue, 23 Jul 2024 14:42:38 +0300 Subject: [PATCH 5/7] docs: add examples and payloads --- docs/CIP/CIP-XXXX/src/cardano-service.yml | 138 +++++++++++++++++++++- 1 file changed, 137 insertions(+), 1 deletion(-) diff --git a/docs/CIP/CIP-XXXX/src/cardano-service.yml b/docs/CIP/CIP-XXXX/src/cardano-service.yml index 6465983..cf2f3c0 100644 --- a/docs/CIP/CIP-XXXX/src/cardano-service.yml +++ b/docs/CIP/CIP-XXXX/src/cardano-service.yml @@ -116,6 +116,32 @@ components: the server and API, helping clients understand the environment they are interacting with. contentType: application/json + payload: + $ref: '#/components/schemas/welcomePayload' + examples: + - + name: Welcome + summary: Welcome message example + payload: + blockchains: + - name: cardano + network: mainnet + extensions: + - name: assetMetadata + config: false + switchable: true + versions: + - '1.0' + - '1.1' + - name: CIP-XXXX + config: + timeout: 10 + switchable: false + versions: + - '1.0' + uri: wss://www.example.com/socketserver + version: '0.1' + genesis: name: Genesis title: Genesis message @@ -148,6 +174,48 @@ components: contentType: application/json payload: $ref: '#/components/schemas/protocolParameterPayload' + examples: + - + name: protocolParameters + summary: Protocol Parameters message example + payload: + epoch: 225 + minFeeA: 44 + minFeeB: 155381 + maxBlockSize: 65536 + maxTxSize: 16384 + maxBlockHeaderSize: 1100 + keyDeposit: '2000000' + poolDeposit: '500000000' + eMax: 18 + nOpt: 150 + a0: 0.3 + rho: 0.003 + tau: 0.2 + decentralisationParam: 0.5 + extraEntropy: + protocolMajorVer: 2 + protocolMinorVer: 0 + minUtxo: '1000000' + minPoolCost: '340000000' + nonce: 1a3be38bcbb7911969283716ad7aa550250226b76a61fc51cc9a9a35d9276d81 + costModels: + plutusV1: + addIntegerCpuArgumentsIntercept: 197209 + addIntegerCpuArgumentsSlope: 0 + plutusV2: + addIntegerCpuArgumentsIntercept: 197209 + addIntegerCpuArgumentsSlope: 0 + priceMem: 0.0577 + priceStep: 7.21e-05 + maxTxExMem: '10000000' + maxTxExSteps: '10000000000' + maxBlockExMem: '50000000' + maxBlockExSteps: '40000000000' + maxValSize: '5000' + collateralPercent: 150 + maxCollateralInputs: 3 + coinsPerUtxoSize: '34482' tip: name: Tip title: Server Tip Message Partial @@ -155,7 +223,25 @@ components: This message partial is added to all server-sent messages and represents the latest current tip of the chain. payload: - $ref: '#/components/schemas/protocolParameterPayload' + $ref: '#/components/schemas/tipPayload' + examples: + - + name: Server Tip message + summary: Cardano Example + payload: + tip: + point: + slot: 127838345 + hash: 9f06ab6ecce25041b3a55db6c1abe225a65d46f7ff9237a8287a78925b86d10e + - + name: Server Tip message + summary: Bitcnoin Example + payload: + tip: + point: + height: 849561 + hash: 00000000000000000000e51f4863683fdcf1ab41eb1eb0d0ab53ee1e69df11bb + eraSummary: name: Era Summary title: Era Summary Server Message Partial @@ -172,6 +258,25 @@ components: slot length, the conversion of a specific point in on-chain time may vary. In order to show and submit transaction times correctly, wallets need to know each era's slot length. + payload: + $ref: '#/components/schemas/eraSummaryPayload' + examples: + - + name: Era Summary Message + summary: Era Summary Message example + payload: + parameters: + epochLength: 432000 + slotLength: 1 + safeZone: 129600 + start: + epoch: 74 + slot: 1598400 + time: '2020-09-11T08:36:51.000Z' + end: + epoch: 102 + slot: 13694400 + time: '2020-12-30T05:04:51.000Z' subscribe: name: Subscribe title: Subscribe message @@ -182,6 +287,37 @@ components: contentType: application/json payload: $ref: '#/components/schemas/subscribePayload' + examples: + - + name: Subscribe + summary: Subscribe message + payload: + type: subscribe + topic: + blockchain: + name: cardano + network: mainnet + signature: OGNiOWIyNGVjOTMxZmY3N2MzYjQxOTY3OWE0YTcwMzczZmVkZmIxNDZmMDE0ODk0Nzg4YjUxMmIzMjE4MDdiYw== + cardano: + credentials: + payment: + - 0d166978f407505f157c9f56fdb3358e60d1589295b2f7a1e66c1574 + stake: + - 82c00414a674fd7e7657aa5634e2086910c2f210e87f22ce880a0063 + points: + - slot: 66268628 + hash: 47b8ec3a58a4a69cb5e3397c36cb3966913882fa8179cae10a5d3f9319c4ae66 + - slot: 87868775 + hash: '074985b22edc01b9579a2e571dc125e044aecf812ee45d50e6fb6fef979fd0d0' + extensions: + - name: resolveTxInput + config: true + version: '1.0' + - name: assetMetadata + config: false + version: '1.0' + timestamp: '2024-06-27T12:34:56Z' + schemas: welcomePayload: type: object From b765bfda5ca30b96082884fd9537235898fe0321 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C4=B1z=C4=B1r=20Sefa=20=C4=B0rken?= Date: Wed, 24 Jul 2024 10:50:11 +0300 Subject: [PATCH 6/7] docs: update AsyncApi servers section --- docs/CIP/CIP-XXXX/src/cardano-service.yml | 26 +++++++++-------------- 1 file changed, 10 insertions(+), 16 deletions(-) diff --git a/docs/CIP/CIP-XXXX/src/cardano-service.yml b/docs/CIP/CIP-XXXX/src/cardano-service.yml index cf2f3c0..25b84c0 100644 --- a/docs/CIP/CIP-XXXX/src/cardano-service.yml +++ b/docs/CIP/CIP-XXXX/src/cardano-service.yml @@ -19,24 +19,18 @@ info: url: 'https://www.apache.org/licenses/LICENSE-2.0' defaultContentType: application/json servers: - cardano-mainnet: - host: 'localhost:8080' + local-server: + host: '127.0.0.1:{port}' protocol: wss - description: Cardano Mainnet API + description: Default instance, when running a local server. + variables: + port: + default: '8080' tags: - - name: 'env:cardano-mainnet' - description: This environment is for Cardano mainnet production - - name: 'visibility:public' - description: This resource is public to all users - cardano-preprod: - host: 'localhost:8080' - protocol: wss - description: Cardano Preprod API - tags: - - name: 'env:cardano-preprod' - description: This environment is for Cardano preprod - - name: 'visibility:public' - description: This resource is public to all users + - name: 'env:local' + description: This environment is for local + - name: 'visibility:private' + description: This resource is locally visible channels: cardano: address: /v1/wallet From b206bf16e008c80cda477fe58fec40e6175b84f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C4=B1z=C4=B1r=20Sefa=20=C4=B0rken?= Date: Wed, 24 Jul 2024 12:02:16 +0300 Subject: [PATCH 7/7] docs: update onGenesis summary --- docs/CIP/CIP-XXXX/src/cardano-service.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/CIP/CIP-XXXX/src/cardano-service.yml b/docs/CIP/CIP-XXXX/src/cardano-service.yml index 25b84c0..effd153 100644 --- a/docs/CIP/CIP-XXXX/src/cardano-service.yml +++ b/docs/CIP/CIP-XXXX/src/cardano-service.yml @@ -68,7 +68,7 @@ operations: channel: $ref: '#/channels/cardano' onGenesis: - summary: On client connection + summary: On client syncing the genesis description: Event received if the client is syncing from the origin action: receive messages: