Release v2024-09-03

cardano-foundation · Sep 4, 2024 · 14a7f5e · 14a7f5e
1 parent 0488397
commit 14a7f5e
Show file tree

Hide file tree

Showing 7 changed files with 9,022 additions and 0 deletions.
diff --git a/api/v2024-09-03/README.md b/api/v2024-09-03/README.md
@@ -0,0 +1,28 @@
+# API Specification
+
+The specification is written using [Swagger 2.0](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) (known today as OpenAPI).
+
+# How to
+
+## Preview a local specification file
+
+Serve the content of this directory through any HTTP server, for instance:
+
+```
+$ python -m SimpleHTTPServer
+Serving HTTP on 0.0.0.0 port 8000 ...
+```
+
+```
+$ python3 -m http.server
+Serving HTTP on 0.0.0.0 port 8000 ...
+```
+
+Then, browse your localhost on port 8000.
+
+
+## Preview a specification file hosted on a remote machine
+
+- Visit https://rebilly.github.io/ReDoc/
+- Provide a URL to the spec file
+- Click on 'TRY IT'
diff --git a/api/v2024-09-03/drep-voting.md b/api/v2024-09-03/drep-voting.md
@@ -0,0 +1,77 @@
+# Specification: DRep voting
+
+This document specifies those aspects of the "Transactions New > Construct" HTTP endpoint that relate to DRep voting in the Voltaire era.
+
+## Voting during delegation and delegate with abstain
+
+The Voltaire voting system interacts with stake pool delegation. The following options are available:
+1. Delegate to a stake pool without participating in the voting system.
+2. Delegate to a stake pool while also participating in the voting system.
+
+After a grace period (6–12 weeks), it will not be possible to withdraw staking rewards under option 1. (The rewards will still be accumulated, and are redeemable again once the user switches to option 2.)
+In order to allow passive participation in the voting system, as part of option 2, there exists the possibility to delegate with `Abstain` which translates always into voting to abstain from any particular decision. While very passive, the spirit of voting system participation still requires that the user actively opts for the voting preference. The other two options include: passing no confidence vote and voting for a particular representative.
+
+The "Transactions New > Construct" HTTP endpoint allows delegation and withdrawals.
+
+Specifically:
+
+1. Creation of a withdrawal transaction in the case of delegation without participating in the voting.
+
+    Example `POST` data for the endpoint:
+
+    ```
+    {
+    ...
+      "withdrawal": "self"
+    ...
+    }
+    ```
+    When in Voltaire era user should expect 403 error with response: "Withdrawals are not possible without participating in the voting. Please re-join the stake pool. If `voting` field is missing abstaining from voting is set."
+
+2. Re-joining with explicit abstain from voting (this is default when `vote` field is missing).
+
+    ```
+    {
+      "delegations":
+           [
+                { "join":
+                  { "pool": "pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm"
+                  , "stake_key_index": "0H"
+                  }
+                }
+           ],
+      "vote": "abstain"
+    }
+    ```
+
+3. Re-joining with no confidence vote.
+
+    ```
+    {
+      "delegations":
+           [
+                { "join":
+                  { "pool": "pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm"
+                  , "stake_key_index": "0H"
+                  }
+                }
+           ],
+      "vote": "no_confidence"
+    }
+    ```
+
+4. Re-joining with a vote casted to a representative by specifying its registered key hash or script hash
+
+    ```
+    {
+      "delegations":
+           [
+                { "join":
+                  { "pool": "pool1wqaz0q0zhtxlgn0ewssevn2mrtm30fgh2g7hr7z9rj5856457mm"
+                  , "stake_key_index": "0H"
+                  }
+                }
+           ],
+      "vote": "drep1jklcrnsdzqp65wjgrg55sy9723kw09mlgvlcp65wjgrg55sy9723mm"
+    }
+    ```
diff --git a/api/v2024-09-03/index.html b/api/v2024-09-03/index.html
@@ -0,0 +1,19 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <title>Cardano Wallet Backend API Documentation</title>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta name="description" content="Swagger-generated API Reference Documentation for Cardano Wallet Backend API" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta property="og:title" content="Cardano Wallet Backend API Documentation" />
+  <meta property="og:description" content="Swagger-generated API Reference Documentation for Cardano Wallet Backend API" />
+  <meta property="og:image" content="https://cardanodocs.com/img/cardano.png" />
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+  <style> body { margin: 0; padding: 0; } </style>
+</head>
+<body>
+  <redoc spec-url="./swagger.yaml"></redoc>
+  <script src="https://cdn.jsdelivr.net/npm/[email protected]/bundles/redoc.standalone.js" async defer></script>
+</body>
+</html>
diff --git a/api/v2024-09-03/metadata-encrypt.md b/api/v2024-09-03/metadata-encrypt.md
@@ -0,0 +1,167 @@
+# Specification: Encrypting and decrypting metadata
+
+This document specifies those aspects of the "Transactions New > Construct" HTTP endpoint that relate to publishing of encrypted metadata.
+In addition "Transactions New > Decode" HTTP endpoint is described in the context of decrypting the metadata.
+
+## Metadata encryption
+
+Encryption of metadata is optional and when chosen the metadata in transaction is to be encrypted
+via AES256CBC according to [CIP-0020][cip0020] and [CIP-0083][cip0083].
+A PKCS#7 padding of payload is used before encryption as the required
+input length must be a multiple of block size, ie., 16 bytes.
+PBKDF2 password stretching is used to get a 32-byte symmetric key
+that is required for the adopted encryption algorithm. In detail, 
+PBKDF2 encryption uses HMAC with the hash algorithm SHA512.
+
+As a consequence the encrypted metadata, not its raw version, is going to be stored in blockchain.
+
+However, in line with [CIP-0020][cip0020] and [CIP-0083][cip0083], only the field `674` of the `metadata` field of the transaction will be affected.
+
+  [cip0020]: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0020
+  [cip0083]: https://github.com/cardano-foundation/CIPs/tree/master/CIP-0083
+
+The "Transactions New > Construct" HTTP endpoint allows the encryption of metadata.
+The "Transactions New > Decode" HTTP endpoint allows for decrypting of the encrypted metadata.
+
+Specifically:
+
+1. Creation of a transaction output that contains a metadata with encryption enabled.
+
+In the `encrypt_metadata` field, passphrase used in encryption is established. `metadata` field to be encrypted is required.
+
+Example `POST` data for the endpoint, ie.,   /wallets/{walletId}/transactions-construct`:
+
+    ```
+    {
+    ...
+      "encrypt_metadata":
+          { "passphrase": "my secret encryption password"
+          },
+      "metadata":
+          { "674" : {
+                      "msg": "raw metadata ... "
+                    }
+          }
+    ...
+    }
+    ```
+
+As a result we get transaction with metadata encrypted:
+    ```
+    {
+    ...
+      "metadata":
+          { "674":
+                   {
+                     "enc": "basic",
+                     "msg":
+                            [
+                              "base64-string 1", "base64-string 2", "base64-string 3" ...
+                            ]
+                   }
+          }
+    ...
+    }
+    ```
+The same is the case for `GET` transaction. `encrypt_metadata` is an object as we might want to introduce
+optional choice of encryption method in the future. In that case the new enhancement to api will be introduced in
+non-intrusive way.
+
+Metadata encryption can be used for shared wallet style when calling `/shared-wallets/{walletId}/transactions-construct` endpoint with the same `POST` payload.
+
+Example:
+    ```
+    {
+    ...
+      "encrypt_metadata":
+          { "passphrase": "metadata-secret"
+          },
+      "metadata":
+          { "674" : {
+                      "msg":"world"
+                    }
+          }
+    ...
+    }
+    ```
+will return (for the example salt "yoDCYXKaVhA=")
+    ```
+    {
+    ...
+      "metadata":
+          { "674" : {
+                      "enc": "basic",
+                      "msg": [ "U2FsdGVkX1/KgMJhcppWEG6t0aUcMqdEJmnSHVOCgpw=" ]
+                    }
+          }
+    ...
+    }
+    ```
+
+Example:
+    ```
+    {
+    ...
+      "encrypt_metadata":
+          { "passphrase": "metadata-secret"
+          },
+      "metadata":
+          { "674" : {
+                      "msg":
+                          [ "Hard times create strong men."
+                          , "Strong men create good times."
+                          , "Good times create weak men."
+                          , "And, weak men create hard times."
+                          ]
+                    }
+          }
+    ...
+    }
+    ```
+will return (for the example salt "XG1cgIw56q8=")
+    ```
+    {
+    ...
+          { "674" : {
+                      "enc": "basic",
+                      "msg":
+                          [ "U2FsdGVkX19cbVyAjDnqr5eksQ9gnxJDz6dWhAaXvZGQl31HdEtTpBa91osBavdQ"
+                          , "xvOJpGuA8vQGJUgn9RVuqFbVxpggHGCspU6Z5BV5j1LlSqnp6GfHFvrTL3sZcZMq"
+                          , "MtOMZSx+d6nPRJL6453wC3rh0cny6SnrEUt9awwxx4PDZk7pDT85h3ygQf1I8fow"
+                          , "tYtj3GY0cBwIHfkRLrsxbg=="
+                          ]
+                    }
+          }
+    ...
+    }
+    ```
+as metadata values have 64-byte limit. In that case the encrypted metadata is encoded in the successive bytes.
+
+
+## Metadata decryption
+
+2. Decoding transaction with encrypted metadata is possible by using the same passphrase as upon encryption in `encrypt_metadata` field. It is realized by calling `POST` on `/wallets/{walletId}/transactions-decode` endpoint with `POST` data:
+
+    ```
+    {
+      "decrypt_metadata":
+          { "passphrase": "my secret encryption password"
+          },
+      "transaction": ....
+    }
+    ```
+
+As a result we get decoded transaction with metadata decrypted:
+    ```
+    {
+    ...
+      "metadata":
+          { "674" : {
+                      "msg": "raw metadata ... "
+                    }
+          }
+    ...
+    }
+    ```
+
+Metadata decryption can be used for shared wallet style when calling `/shared-wallets/{walletId}/transactions-decode` endpoint with the same `POST` payload.
diff --git a/api/v2024-09-03/mint-burn.md b/api/v2024-09-03/mint-burn.md
@@ -0,0 +1,98 @@
+# Specification: Minting and Burning
+
+This document specifies those aspects of the "Transactions New > Construct" HTTP endpoint that relate to minting and burning native assets.
+
+## Reference inputs for minting scripts
+
+[Reference inputs][ref] are inputs of a transaction that are not spent; instead, the outputs they reference are made available to, say, Plutus validator scripts for inspection.
+
+  [ref]: https://cips.cardano.org/cips/cip31/#referenceinputs
+
+In particular, with reference inputs, we can define a minting script in one transaction and reference the script in subsequent transaction(s). In other words, we can save space on the blockchain by defining a script once and referencing it later, instead of including a full copy of the script with every transaction.
+
+The "Transactions New > Construct" HTTP endpoint allows the creation and use of reference inputs.
+
+Specifically:
+
+1. Creation of a transaction output that contains a minting script and is suitable for use as reference input.
+
+    In the `reference_policy_script_template` field, you can optionally add a script template. The HTTP endpoint will map this script template into a script using the wallet's policy public key, and this script will be included in the first transaction output (i.e. at index `0`) of the transaction. For Shelley-style wallets, the script template must contain a single cosigner only, but it may include time locks.
+
+    Example `POST` data for the endpoint:
+
+    ```
+    {
+    ...
+      "reference_policy_script_template":
+          { "all":
+             [ "cosigner#0",
+               { "active_from": 120 }
+             ]
+          },
+    ...
+    }
+    ```
+
+2. Getting policy id using the same script template as in point 1. It is realized by calling `POST` on `/wallets/{walletId}/policy-id` endpoint with `POST` data:
+
+    ```
+    {
+      "policy_script_template":
+          { "all":
+             [ "cosigner#0",
+               { "active_from": 120 }
+             ]
+          }
+    }
+    ```
+
+3. Using a refence input that contains a minting script.
+
+    In the `mint_burn` field, the array element contains `reference_input` and `policy_id`. The first field specifies a transaction input (pair of transaction ID and output index) which will be added as a reference input and is assumed to contain the minting script. (If the corresponding output was created using the method above, the appropriate output index is `0`). The `policy_id` field is obtained from the response of request realized in point 2.
+
+    Example `POST` data for the endpoint with reference input:
+
+    ```
+    {
+    ...
+    "mint_burn": [{
+        "reference_input":
+            { "id": "464917d2bac71df96269c2d7c34dcb83183b8a3a3253c06e9d6a8bd0681422c9",
+              "index": 0
+            },
+        "policy_id": "7191ae0e1286891fe5c027a5dc041b7401689938e18e14ec83cf74fb",
+        "asset_name": "ab12",
+        "operation":
+            { "mint" :
+                  { "receiving_address": #{destination},
+                     "quantity": 10000
+                  }
+            }
+    }]
+    ...
+    }
+    ```
+
+    For contrast: Example `POST` data for the endpoint with script template:
+
+    ```
+    {
+    ...
+    "mint_burn": [{
+        "policy_script_template":
+            { "all":
+               [ "cosigner#0",
+                 { "active_from": 120 }
+               ]
+            },
+        "asset_name": "ab12",
+        "operation":
+            { "mint" :
+                  { "receiving_address": #{destination},
+                     "quantity": 10000
+                  }
+            }
+    }]
+    ...
+    }
+    ```