Skip to content

Commit

Permalink
Release v2024-05-05
Browse files Browse the repository at this point in the history
  • Loading branch information
Cardano Wallet Documentation Bot committed May 10, 2024
1 parent 1c7647d commit 6d55aeb
Show file tree
Hide file tree
Showing 7 changed files with 8,667 additions and 0 deletions.
28 changes: 28 additions & 0 deletions api/v2024-05-05/README.md
View file
Original file line number Diff line number Diff line change
@@ -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'
77 changes: 77 additions & 0 deletions api/v2024-05-05/drep-voting.md
View file
Original file line number Diff line number Diff line change
@@ -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"
}
```
19 changes: 19 additions & 0 deletions api/v2024-05-05/index.html
View file
Original file line number Diff line number Diff line change
@@ -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/redoc@2.0.0-rc.23/bundles/redoc.standalone.js" async defer></script>
</body>
</html>
124 changes: 124 additions & 0 deletions api/v2024-05-05/metadata-encrypt.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,124 @@
# 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 AEAD scheme using ChaCha20 and Poly1305 (see [RFC 7539][ref]). 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.

[ref]: https://datatracker.ietf.org/doc/html/rfc7539

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": "raw metadata"
...
}
```

As a result we get transaction with metadata encrypted:
```
{
...
"metadata": "metadata encrypted"
...
}
```
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
nonintrusive 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": {"1":"hello"}
...
}
```
will return
```
{
...
"metadata": {"0":"0x0aa4f9a016215f71ef007b60601708dec0d10b4ade6071b387295f95b4"}
...
}
```

Example:
```
{
...
"encrypt_metadata":
{ "passphrase": "metadata-secret"
},
"metadata":
{ "1": "Hard times create strong men."
, "2": "Strong men create good times."
, "3": "Good times create weak men."
, "4": "And, weak men create hard times."
}
...
}
```
will return
```
{
...
"metadata":
{ "0": "0x0aa4f9a016217f75f10834367493f6d7e74197417ca25c7615cae02bc345382906fb6990daf8f138b2d9192e057d0d0b555f9d5fb287abb1842928c90f26e597"
, "1": "0x559ee85f00f1588b3ee32e81dc4c84aee208a10c1eec97fffe6e0e66c69d4e0b1e3e22d7edc1618df3b20b484527d86bc3bebad4295a2ad888d034b5fec38077"
, "2": "0x8d42154f681230124c64630ea68b841aec22f0530ec830cb662d59ef423ef23d7ff3"
}
...
}
```
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": "raw metadata"
...
}
```

Metadata decryption can be used for shared wallet style when calling `/shared-wallets/{walletId}/transactions-decode` endpoint with the same `POST` payload.
98 changes: 98 additions & 0 deletions api/v2024-05-05/mint-burn.md
View file
Original file line number Diff line number Diff line change
@@ -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
}
}
}]
...
}
```
Loading

0 comments on commit 6d55aeb

Please sign in to comment.