swagger: Add balanceTx

specifications/api/swagger.yaml

@@ -267,13 +267,113 @@ x-addressState: &addressState
     - used
     - unused
 
+x-txType: &txType
+  type: string
+  pattern: "^Tx AlonzoEra$"
+
+x-txDescription: &txDescription
+  description: A description of transaction
+  type: string
+  minLength: 0
+  maxLength: 256
+  example: "Asset minting transaction"
+
+x-txInNode: &txInNode
+  type: string
+  pattern: "^[0-9abcdef]+#[0-9]+$"
+  minLength: 66
+  maxLength: 68
+  example: 2f8cd2ef706e5500307636b8477198ee2f204c4181b53c507f46d195140493cb#1
+
+x-dataHash: &dataHash
+  type: string
+  format: hex
+  minLength: 64
+  maxLength: 64
+  example: ca54c8836c475a77c6914b4fd598080acadb0f0067778773484d2c12ae7dc756
+
+x-adaQuantity: &adaQuantity
+  type: integer
+  minimum: 0
+  maximum: 45000000000000000
+
+x-assetQuantity: &assetQuantity
+  type: integer
+  description: |
+    Number of assets for the given `policy_id` and `asset_name`.
+  minimum: 0
+
+x-assetValueNode: &assetValueNode
+  description:
+     Map of asset values along with their quantities.
+     assetName in field name is expected (max lenght 64-character hex-encoded text)
+  type: object
+  additionalProperties: *assetQuantity
+  # Note: propertyNames pattern not supported in current OpenAPI version.
+  # propertyNames:
+  #   pattern: '^(assetName)$'
+  example:
+    - {"asset1": 12, "asset2": 33}
+
+x-valueNode: &valueNode
+  nullable: false
+  oneOf:
+    - <<: *adaQuantity
+      title: ada coin
+    - <<: *assetValueNode
+      title: asset value
+
+x-valueNodes: &valueNodes
+  description:
+     Map of values along with their quantities. Can be lovelace or asset.
+     In the former case 'lovelace' name is expected.
+     In the latter case assetPolicyId name is expected (56-character hex-encoded text)
+  type: object
+  additionalProperties: *valueNode
+  # Note: propertyNames pattern not supported in current OpenAPI version.
+  # propertyNames:
+  #   pattern: '^(lovelace)|(assetPolicyId)$'
+  example:
+    - {"lovelace": 1423}
+    - {"lovelace": 1423, "7191ae0e1286891fe5c027a5dc041b7401689938e18e14ec83cf74fb": {"asset1": 12, "asset2": 33}}
+
+x-txOutNodeWithoutDatum: &txOutNodeWithoutDatum
+  description: tx out without datum
+  type: object
+  required:
+    - address
+    - value
+  properties:
+    address: *addressId
+    value: *valueNodes
+
+x-txOutNodeWithDatum: &txOutNodeWithDatum
+  description: tx out without datum
+  type: object
+  required:
+    - address
+    - data
+    - value
+  properties:
+    address: *addressId
+    data: *dataHash
+    value: *valueNodes
+
+x-txOutNode: &txOutNode
+  nullable: false
+  oneOf:
+    - <<: *txOutNodeWithDatum
+      title: tx out with datum
+    - <<: *txOutNodeWithoutDatum
+      title: tx out without datum
+
 x-stakePoolId: &stakePoolId
   type: string
   format: hex|bech32
   example: pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm
   description: A unique identifier for the pool.
 
-x-walletAccountPubkey: &walletAccountPubkey
+x-walletAccountXPubkey: &walletAccountXPubkey
   description: An extended account public key (public key + chain code)
   type: string
   format: hex
@@ -288,7 +388,7 @@ x-cosigner: &cosigner
 x-cosigners: &cosigners
   description: Map of cosigners and their account public keys. Use key as in &cosigner, eg. "cosigner#"
   type: object
-  additionalProperties: *walletAccountPubkey
+  additionalProperties: *walletAccountXPubkey
   # Note: propertyNames pattern not supported in current OpenAPI version.
   # propertyNames:
   #   pattern: '^(cosigner#)[0-9]+$'
@@ -303,7 +403,7 @@ x-self: &self
 x-accountPubkeyOrSelf: &accountPubkeyOrSelf
   nullable: false
   oneOf:
-    - <<: *walletAccountPubkey
+    - <<: *walletAccountXPubkey
       title: public key
     - <<: *self
       title: self
@@ -826,12 +926,6 @@ x-walletBalance: &walletBalance
       <<: *amount
       description: Total Ada balance (available balance plus pending change and reward balance).
 
-x-assetQuantity: &assetQuantity
-  type: integer
-  description: |
-    Number of assets for the given `policy_id` and `asset_name`.
-  minimum: 0
-
 x-walletAsset: &walletAsset
   description: |
     An asset on the Cardano blockchain. An asset is uniquely identified by
@@ -1268,10 +1362,19 @@ x-transactionResolvedWithdrawals: &transactionResolvedWithdrawals
       amount: *amount
 
 x-serialisedTransaction: &serialisedTransaction
-  description: CBOR transaction data, base64-encoded.
+  description: |
+    The CBOR-encoded transaction, represented in base-64. This always
+    includes the transaction body and the witness set, even if empty.
   type: string
   format: base64
 
+x-serialisedTransactionHex: &serialisedTransactionHex
+  description: |
+    The CBOR-encoded transaction, represented in hexadecimal (base-16). This always
+    includes the transaction body and the witness set, even if empty.
+  type: string
+  format: hex
+
 x-signedTransactionBlob: &signedTransactionBlob
   description: Signed transaction message binary blob.
   type: string
@@ -2267,7 +2370,7 @@ components:
         - account_public_key
       properties:
         name: *walletName
-        account_public_key: *walletAccountPubkey
+        account_public_key: *walletAccountXPubkey
         address_pool_gap: *walletAddressPoolGap
 
     ApiWalletOrAccountPostData: &ApiWalletOrAccountPostData
@@ -2369,7 +2472,7 @@ components:
         - payment_script_template
       properties:
         name: *walletName
-        account_public_key: *walletAccountPubkey
+        account_public_key: *walletAccountXPubkey
         account_index: *derivationSegment
         payment_script_template: *scriptTemplateEntry
         delegation_script_template: *scriptTemplateEntry
@@ -2793,6 +2896,47 @@ components:
             - <<: *transactionWithdrawalRequestSelf
             - <<: *transactionRedemptionRequest
 
+    ApiTransactionExtended: &ApiTransactionExtended
+      type: object
+      required:
+        - cborHex
+        - description
+        - type
+      properties:
+        cborHex: *serialisedTransactionHex
+        description: *txDescription
+        type: *txType
+
+    ApiExternalInput: &ApiExternalInput
+      type: object
+      required:
+        - txIn
+        - txOut
+      properties:
+        txIn: *txInNode
+        txOut: *txOutNode
+
+    ApiExternalInputs: &ApiExternalInputs
+      description: A flat list of node compliant inputs.
+      type: array
+      items: *ApiExternalInput
+
+    ApiTransactionSignatories: &ApiTransactionSignatories
+      description: A flat list of account public keys of parties engaged in transaction.
+      type: array
+      items: *walletAccountXPubkey
+
+    ApiBalanceTransactionPostData: &ApiBalanceTransactionPostData
+      type: object
+      required:
+        - transaction
+        - signatories
+        - inputs
+      properties:
+        transaction: *ApiTransactionExtended
+        signatories: *ApiTransactionSignatories
+        inputs: *ApiExternalInputs
+
     # ADP-908 Deprecated
     ApiPostTransactionDataByron: &ApiPostTransactionDataByron
       type: object
@@ -3980,6 +4124,19 @@ x-errAssetNotPresent: &errAssetNotPresent
       type: string
       enum: ['asset_not_present']
 
+x-errOutputsAlreadyCovered: &errOutputsAlreadyCovered
+  <<: *responsesErr
+  title: outputs_already_covered
+  properties:
+    message:
+      type: string
+      description: |
+        Occurs when requesting balancing of a transaction
+        that has already all outputs covered.
+    code:
+      type: string
+      enum: ['outputs_already_covered']
+
 x-responsesErr400: &responsesErr400
   400:
     description: Bad Request
@@ -4462,6 +4619,36 @@ x-responsesConstructTransaction: &responsesConstructTransaction
       application/json:
         schema: *ApiConstructTransaction
 
+x-responsesBalanceTransaction: &responsesBalanceTransaction
+  400:
+    description: Bad Request
+    content:
+      application/json:
+        schema:
+          oneOf:
+            - <<: *errBadRequest
+  403:
+    description: Forbidden
+    content:
+      application/json:
+        schema:
+          oneOf:
+            - <<: *errInvalidWalletType
+            - <<: *errAlreadyWithdrawing
+            - <<: *errUtxoTooSmall
+            - <<: *errCannotCoverFee
+            - <<: *errNotEnoughMoney
+            - <<: *errTransactionIsTooBig
+            - <<: *errOutputsAlreadyCovered
+  <<: *responsesErr404WalletNotFound
+  <<: *responsesErr406
+  <<: *responsesErr415UnsupportedMediaType
+  202:
+    description: Accepted
+    content:
+      application/json:
+        schema: *ApiConstructTransaction
+
 x-responsesSignTransaction: &responsesSignTransaction
   <<: *responsesErr400
   403:
@@ -5219,6 +5406,25 @@ paths:
             schema: *ApiSignTransactionPostData
       responses: *responsesSignTransaction
 
+  /wallets/{walletId}/transactions-balance:
+    post:
+      operationId: balanceTransaction
+      tags: ["Transactions New"]
+      summary: Balance
+      description: |
+        <p align="right">status: <strong>under development</strong></p>
+
+        Balance a transaction body, add needed inputs, and
+        create a transaction to be signed from the wallet.
+      parameters:
+        - *parametersWalletId
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: *ApiBalanceTransactionPostData
+      responses: *responsesBalanceTransaction
+
   /wallets/{walletId}/addresses:
     get:
       operationId: listAddresses