swagger: Further draft revisions

Some reordering required to please the openapi-spec-validator.
cardano-foundation · Jan 14, 2021 · 55c24ec · 55c24ec
1 parent 4c69843
commit 55c24ec
Showing 1 changed file with 216 additions and 25 deletions.
diff --git a/specifications/api/swagger.yaml b/specifications/api/swagger.yaml
@@ -437,26 +437,93 @@ x-assetPolicyItem: &assetPolicyItem
   type: string
   description: |
     The asset on-chain type which acts as a sub-identifier within a policy.
-    Typically an empty string for policies with a single fungible asset item.
-  format: base64
+
+    For policies with a single fungible asset item, this is typically
+    an empty string.
+
+    This value can be up to 32 bytes of arbitrary data (which is 64
+    hexadecimal digits).
+  # fixme: (remove this note) I changed it to hex from base64, the reason is below.
+  format: hex
+  maxLength: 64
+  examples:
+    - ""
+    - "fa1c818d060ba1"
 
 x-assetPolicyId: &assetPolicyId
   type: string
   description: |
-    A unique identifier of the asset policy. It identifies who is able to forge and burn
-    new assets of this kind.
-  format: base64
+    A unique identifier of the asset's monetary policy. The policy
+    controls how assets of this kind are created and destroyed.
+
+    The contents are the blake2b-256 hash of the monetary policy
+    script, encoded in hexadecimal.
+  # fixme: (remove this note) I changed it from base64, because
+  # although the hex encoding is longer, it's easier to work with in
+  # urls, etc, and has fixed length.
+  format: hex
+  minLength: 64
+  maxLength: 64
+  example: 65ab82542b0ca20391caaf66a4d4d7897d281f9c136cd3513136945b69b042a7
+
+x-assetPolicyItemDisplayName: &assetPolicyItemDisplayName
+  type: string
+  description: |
+    A label for the asset suitable for presentation to users.
+
+    If the asset has a known metadata name, then this is used.
+
+    Otherwise, the display name is taken from the policy item
+    sub-identifier.
+
+    If this sub-identifier is valid UTF-8 text, and non-empty, then it
+    is shown as-is. If the identifier cannot be decoded as UTF-8 text,
+    then the display name will be the sub-identifier encoded in
+    hexadecimal, starting with 0x.
+
+    If the sub-identifier is empty, then the policy ID is used,
+    encoded in hexadecimal, starting with 0x.
+  example: SWAGGER
 
 x-assetName: &assetName
   type: string
   description: |
     A human-readable name for the asset. Good for display in user interfaces.
+  # fixme: make example values coherent with each other
+  example: SwaggerCoin
 
 x-assetAcronym: &assetAcronym
   type: string
   description: |
-    A human-readable name for the asset. Good for display in user interfaces.
-  format: base64
+    A human-readable short name for the asset. Good for display in
+    user interfaces.
+  example: API
+
+# fixme: (remove this note) Note: this a very basic scheme for defining
+# units, which will work in many cases.
+x-assetUnit: &assetUnit
+  type: object
+  description: |
+    Defines a larger unit for the asset, in the same way Ada is the
+    larger unit of Lovelace.
+  required:
+    - decimals
+    - name
+  properties:
+    decimals:
+      type: integer
+      description: |
+        The number of digits after the decimal point.
+      minimum: 0
+      maximum: 19
+    name:
+      type: string
+      description: |
+        The human-readable name for the larger unit of the asset. Used
+        for display in user interfaces.
+  example:
+    name: DOLLAR
+    decimals: 2
 
 x-assetUrl: &assetUrl
   type: string
@@ -481,6 +548,19 @@ x-assetDescription: &assetDescription
       type: string
       description: The description, in English (en).
 
+x-assetPolicyItemMetadata: &assetPolicyItemMetadata
+  type: object
+  description: |
+    Additional information about the asset which is not stored
+    on chain. This data is fetched from an external source.
+  properties:
+    name: *assetName
+    acronym: *assetAcronym
+    unit: *assetUnit
+    url: *assetUrl
+    logo: *assetLogo
+    description: *assetDescription
+
 x-walletMnemonicSentence: &walletMnemonicSentence
   description: A list of mnemonic words
   type: array
@@ -582,9 +662,12 @@ x-assetQuantity: &assetQuantity
 x-walletAsset: &walletAsset
   description: |
     An asset on the Cardano blockchain. An asset is uniquely identified by
-    its `type` and `policy_id` (also called _asset id_). Two assets with the same `policy_item`
-    and `policy_id` are fungible together (that is, they are interchangeable).
-    Yet, different assets with a same `policy_id`  but different `policy_item` are treated as separate assets.
+    its `policy_item` and `policy_id` (together, these form the _asset id_).
+
+    Two assets with the same `policy_item` and `policy_id` are
+    interchangeable. Yet, different assets with a same `policy_id` but
+    different `policy_item` are treated as separate assets, as are two
+    assets with the same `policy_item` but different `policy_id`.
   type: object
   required:
     - policy_item
@@ -596,10 +679,47 @@ x-walletAsset: &walletAsset
     quantity: *assetQuantity
 
 x-walletAssets: &walletAssets
-  description: Wallet assets
+  description: A flat list of assets.
   type: array
   items: *walletAsset
 
+x-assetForge: &assetForge
+  type: object
+  required:
+    - policy_item
+    - policy_id
+    - quantity
+  properties:
+    policy_id: *assetPolicyId
+    policy_item: *assetPolicyItem
+    quantity:
+      type: integer
+      description: |
+        Positive values mean creation and negative values mean
+        destruction.
+
+x-walletAssetsBalance: &walletAssetsBalance
+  description: |
+    Current non-Ada asset holdings of the wallet.
+
+    The amount of assets available to spend may be less than the total
+    unspent assets due to transaction change amounts which are yet to
+    be fully confirmed (pending).
+  type: object
+  required:
+    - available
+    - total
+  properties:
+    available:
+      <<: *walletAssets
+      description: |
+        Available UTxO asset balances (funds that can be spent without
+        condition).
+    total:
+      <<: *walletAssets
+      description: |
+        Total asset balances (available balances plus pending change balances).
+
 x-byronWalletBalance: &byronWalletBalance
   description: Byron wallet's current balance(s)
   type: object
@@ -676,8 +796,12 @@ x-addresses: &addresses
 
 x-transactionInputs: &transactionInputs
   description: |
-    A list of transaction inputs. `assets` and `address` are always present for `outgoing`
-    transactions and are generally absent for `incoming` transactions.
+    A list of transaction inputs.
+
+    `assets` and `address` are always present for `outgoing`
+    transactions but generally absent for `incoming`
+    transactions. This information is present on the Cardano explorer,
+    but is not tracked by the wallet.
   type: array
   minItems: 0
   items:
@@ -706,7 +830,7 @@ x-transactionOutputs: &transactionOutputs
     properties:
       address: *addressId
       amount: *amount
-      assets: *walletAsset
+      assets: *walletAssets
 
 x-delegationAction: &delegationAction
   description: |
@@ -790,6 +914,19 @@ x-transactionWithdrawals: &transactionWithdrawals
       stake_address: *stakeAddress
       amount: *amount
 
+x-transactionForge: &transactionForge
+  description: |
+    Assets forged/destroyed, minted/unminted, created/destroyed,
+    whatever the correct terminology is.
+
+    The forge amount contributes to the total transaction value.
+
+    Positive values denote creation of assets and negative values
+    denote the reverse.
+  type: array
+  minItems: 0
+  items: *assetForge
+
 x-derivationSegment: &derivationSegment
   description: |
     An individual segment within a derivation path.
@@ -1435,12 +1572,14 @@ components:
       required:
         - id
         - amount
+        - assets
         - fee
         - deposit
         - direction
         - inputs
         - outputs
         - withdrawals
+        - forge
         - status
       properties:
         id: *transactionId
@@ -1455,6 +1594,14 @@ components:
 
             For incoming transaction, it represents the total amount of Ada received to
             addresses that belong to the wallet.
+        assets:
+          <<: *walletAssets
+          description: |
+            An amount of non-Ada assets spent or received, from the
+            perspective of the wallet.
+
+            Note that transaction fees and delegation rewards are
+            always denominated in Ada.
         fee: *amount
         deposit: *amount
         inserted_at: *transactionInsertedAt
@@ -1465,6 +1612,7 @@ components:
         inputs: *transactionInputs
         outputs: *transactionOutputs
         withdrawals: *transactionWithdrawals
+        forge: *transactionForge
         status: *transactionStatus
         metadata: *transactionMetadata
 
@@ -1512,7 +1660,6 @@ components:
         - id
         - address_pool_gap
         - balance
-        - assets
         - delegation
         - name
         - state
@@ -1521,7 +1668,7 @@ components:
         id: *walletId
         address_pool_gap: *walletAddressPoolGap
         balance: *walletBalance
-        assets: *walletAssets
+        assets: *walletAssetsBalance
         delegation: *ApiWalletDelegation
         name: *walletName
         passphrase: *walletPassphraseInfo
@@ -1546,21 +1693,18 @@ components:
         state: *walletState
         tip: *blockReference
 
+    # Same as *walletAsset plus display_name and metadata
     ApiAsset: &ApiAsset
-      type: object
       required:
-        - policy_id
         - policy_item
+        - policy_id
         - quantity
       properties:
         policy_id: *assetPolicyId
         policy_item: *assetPolicyItem
         quantity: *assetQuantity
-        name: *assetName
-        acronym: *assetAcronym
-        url: *assetUrl
-        logo: *assetLogo
-        description: *assetDescription
+        display_name: *assetPolicyItemDisplayName
+        metadata: *assetPolicyItemMetadata
 
     ApiWalletMigrationInfo: &ApiWalletMigrationInfo
       type: object
@@ -2164,6 +2308,25 @@ x-parametersMinWithdrawal: &parametersMinWithdrawal
     type: integer
     minimum: 1
 
+x-parametersPolicyId: &parametersPolicyId
+  in: path
+  name: policyId
+  required: true
+  schema:
+    type: string
+    format: hex
+    maxLength: 64
+    minLength: 64
+
+x-parametersPolicyItem: &parametersPolicyItem
+  in: path
+  name: policyItem
+  required: true
+  schema:
+    type: string
+    format: hex
+    maxLength: 64
+
 #############################################################################
 #                                                                           #
 #                                RESPONSES                                  #
@@ -3392,10 +3555,18 @@ paths:
       description: |
         <p align="right">status: <strong>under development</strong></p>
 
-        List all assets available in the wallet, with their metadata if any.
+        List all assets associated with the wallet, and their metadata
+        if known.
+
+        An asset is _associated_ with a wallet if it is involved in a
+        transaction of the wallet.
+      parameters:
+        - *parametersWalletId
       responses: *responsesListAssets
 
-  /wallets/{walletId}/assets/{policy_id}/{policy_item}:
+  # fixme: Perhaps remove policyItem and have a single endpoint which
+  # returns all assets belonging to the policy. See getAsset2
+  /wallets/{walletId}/assets/{policyId}/{policyItem}:
     get:
       operationId: getAsset
       tags: ["Assets"]
@@ -3404,8 +3575,28 @@ paths:
         <p align="right">status: <strong>under development</strong></p>
 
         Fetch a single asset from its `policy_id` and `policy_item`, with its metadata if any.
+
+        The asset must be associated with the wallet.
+      parameters:
+        - *parametersWalletId
+        - *parametersPolicyId
+        - *parametersPolicyItem
       responses: *responsesGetAsset
 
+  /wallets/{walletId}/assets/{policyId}:
+    get:
+      operationId: getAsset2
+      tags: ["Assets"]
+      summary: Get Asset (variation)
+      description: |
+        <p align="right">status: <strong>under development</strong></p>
+
+        Fetch all assets from the given `policy_id` associated with the wallet.
+      parameters:
+        - *parametersWalletId
+        - *parametersPolicyId
+      responses: *responsesListAssets
+
   /wallets/{walletId}/statistics/utxos:
     get:
       operationId: getUTxOsStatistics