Add built site dir to repo root

doc/read-the-docs-site/conf.py

@@ -7,7 +7,7 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = 'Credential Manager'
-copyright = '2024, Input Output Global Ltd.'
+copyright = 'Input Output Global Ltd.'
 author = 'Jamie Bertram, Thomas Vellekoop, Tomasz Rybarczyk'
 
 # -- General configuration ---------------------------------------------------

docs/_sources/background/cc-credentials.rst.txt

@@ -0,0 +1,149 @@
+.. _cc_credentials:
+
+Constitutional Committee Credentials
+====================================
+
+Having covered credentials in general, let's take a closer look at
+Constitutional Committee credentials. Members of the constitutional committee
+have two credentials to manage: a cold credential and a hot credential.
+
+Cold Credentials
+----------------
+
+The cold credential is used to identify committee members, and can be thought
+of as a sort of "primary" credential. The cold credential is what you see if
+you query the current committee state from a Cardano node:
+
+.. code-block:: bash
+
+   $ cardano-cli conway query committee-state
+   {
+      "committee": {
+         "keyHash-5e86313210aef13297187c38c98abb632678906230f555a1bf0a647a": {
+               "expiration": 100,
+               "hotCredsAuthStatus": {
+                  "tag": "MemberNotAuthorized"
+               },
+               "nextEpochChange": {
+                  "tag": "NoChangeExpected"
+               },
+               "status": "Active"
+         }
+      },
+      "epoch": 16,
+      "threshold": 0.67
+   }
+
+This example shows a committee with one member identified by the cold
+credential ``keyHash-5e86313210aef13297187c38c98abb632678906230f555a1bf0a647a``.
+The cold credential is used to authorize transactions that publish two types of
+certificates:
+
+1. Hot credential authorization certificates, which have the effect of
+   registering a hot credential to vote on behalf of the cold credential.
+2. Committee resignation certificates, which have the effect of removing the
+   member from the committee.
+
+Both of these are exceptional events which should occur infrequently, if at all
+(a hot credential must be authorized at least once to allow for voting).
+
+A cold credential can be added to the committee in one of two ways:
+
+1. A governance action proposing to add it to the committee is ratified and
+   enacted.
+2. It is hard-coded in the Conway Genesis configuration file.
+
+Both of these processes are beyond the control of the bearer of the cold
+credential. In the first case, it is up to the electorate (DReps and SPOs) of
+Cardano whether or not the governance action is ratified. In the second case,
+there is only one Conway Genesis file, and it cannot be altered (though in
+theory new committee members *could* be injected in a subsequent hard-fork
+event, though this is highly unlikely, and would still be subject to approval
+from the DReps and SPOs).
+
+This makes the cold credential extremely security critical, as losing control
+over it can only be remedied by the member being voted out of the committee in
+the best case, or the entire committee being disbanded via a no confidence
+governance action in the worst case. Either way, the member is unlikely to be
+re-elected after such a display of negligence. One of the purposes of this
+credential management system is to provide additional layers of security which
+help prevent this sort of situation and give better options for recovery if
+necessary.
+
+Hot Credentials
+---------------
+
+The hot credential is required to vote as a committee member. It is the
+"workhorse" credential, in that it is expected to be used frequently for
+everyday business. This is in contrast to the cold credential, which is expected
+to be used only in exceptional circumstances. A hot credential must be
+authorized by the cold credential, and also appears in the committee state
+queried from a Cardano node:
+
+.. code-block:: bash
+
+   $ cardano-cli conway query committee-state
+   {
+      "committee": {
+         "keyHash-5e86313210aef13297187c38c98abb632678906230f555a1bf0a647a": {
+               "expiration": 100,
+               "hotCredsAuthStatus": {
+                  "contents": {
+                     "keyHash": "e394a160b9f1345b7b84cd25f0a3f1d12cb0c9835a4167f7dc5b52ca"
+                  },
+                  "tag": "MemberAuthorized"
+               },
+               "nextEpochChange": {
+                  "tag": "NoChangeExpected"
+               },
+               "status": "Active"
+         }
+      },
+      "epoch": 16,
+      "threshold": 0.67
+   }
+
+This example shows the same committee member as before, only this time they
+have authorized a hot credential, namely
+``{ "keyHash": "e394a160b9f1345b7b84cd25f0a3f1d12cb0c9835a4167f7dc5b52ca" }``.
+
+Compared with the cold credential, a hot credential is relatively cheap to
+replace: when a new hot credential is authorized by the cold credential, it
+invalidates the existing hot credential, taking its place. This is entirely
+within the control of the bearer of the cold credential, and comes into effect
+as soon as the authorization certificate is published on chain via a
+transaction. That notwithstanding, it is still undesirable to replace the hot
+credential if it can be avoided. This is because doing so requires using the
+cold credential, which is meant to be used sparingly - ideally never after the
+hot credential is authorized. Replacing hot credentials frequently is also
+highly visible activity and may negatively impact the reputation of the
+committee member within the community - remember, the community has the power
+to depose individual committee members or the whole committee if they lose
+faith in them. This system also offers greater flexibility for managing the hot
+credential without having to replace it.
+
+Note on Terminology
+-------------------
+
+The names "hot" and "cold" come from the terms "hot key" and "cold key". A cold
+key is a key that is only used to authorize a hot key to act on its behalf, but
+is otherwise kept in "cold storage" (e.g. on a computer physically separated
+from the internet, or a non-digital medium) for security purposes. The hot
+credential is used to conduct everyday business, and may be kept in "hot" or
+"live" storage so that it is easier to access. The benefit of such a setup is
+that it offers many of the security benefits of keeping keys in cold storage
+while mitigating the drawbacks of doing so - namely it is not convenient to use
+the cold key frequently.
+
+Analogously, the cold committee credential is used only for hot credential
+authorization and committee resignation, both of which are exceptional
+activities, while the hot credential is used for everyday LOB work. Indeed, if
+public key credentials are used for both, the analogy is perfect. However, the
+analogy breaks down somewhat when script credentials are used, as there is no
+notion of keeping private keys in hot or cold storage with script credentials.
+The concept is still applicable though: The cold credential is used rarely, the
+hot credential is used often. Therefore, any private data needed to activate
+the cold credential should be treated like a cold private key and kept in cold
+storage. For example, if the cold credential requires the transaction to be
+signed by multiple private keys, as is the case with this system, those private
+keys should be treated like cold keys, because that is what they are.

docs/_sources/background/credentials.rst.txt

@@ -0,0 +1,115 @@
+.. _cardano_credentials:
+
+Cardano Credentials
+===================
+
+On Cardano, a credential is a piece of information that anyone can use to
+verify the legitimacy of changes to the blockchain described by a transaction.
+Credentials are used for many purposes in the Conway era, including:
+
+* Consuming UTxOs (Payment credentials)
+* Withdrawing staking rewards (staking credentials)
+* Publishing governance certificates (DRep, Cold Committee credentials)
+* Voting (DRep, Hot Committee credentials)
+
+There are two types of credentials: public key credentials and script
+credentials.
+
+Public Key Credentials
+----------------------
+
+Public Key Credentials use
+`public-key cryptography <https://en.wikipedia.org/wiki/Public-key_cryptography>`_
+to prove that transactions were authorized by the appropriate parties. If a
+transaction requires authorization from the bearer of a public key credential,
+it must be **signed** by them. To sign a transaction, the owner of the public
+key attaches a **signature** to the transaction. A signature is a cryptographic
+digest of the transaction produced using the public key's associated **private
+key**. The signature proves that the transaction was witnessed by the
+credential owner, and the public key can be used by anyone to verify the
+signature. There are several advantages to public key credentials:
+
+* They are easy to create
+* Provided that a secure source of randomness was used to generate the key
+  pair, and that the private key is managed securely, they provide quite good
+  security without much room for exploitation.
+* They are cheap to verify and small in size, all of which lowers transaction
+  fees significantly compared with script credentials.
+* They are based on a mature and standard cryptographic algorithm (Ed25519).
+
+However, they also have drawbacks:
+
+* They are single points of failure. If the private key is lost or stolen, the
+  legitimate owner of the credential will be unable to authorize transactions,
+  nor will they be able to stop thieves from impersonating them.
+* They are not sufficient for setups requiring authorization from multiple
+  individuals.
+* They are opaque on their own - they do not contain identifiable information.
+  Depending on the application, this can also be an advantage, but not when
+  transparency is desired.
+* They may be difficult to change if a credential is compromised. For example,
+  all UTxOs owned by a payment key would need to be sent to the new one,
+  costing the owner ADA in fees. Other types of credentials, particularly
+  constitutional committee cold credentials, are far more difficult to change.
+
+All of these drawbacks make public key credentials generally inappropriate for
+organizations which distribute and delegate authority to staff or other
+types of trustees.
+
+Script Credentials
+------------------
+
+Script credentials are executable programs which encode custom authorization
+rules. These are also informally referred to as "smart contracts." To authorize
+a transaction, the program receives a summary of the transaction it is
+authorizing and is executed. If the program terminates without raising an
+exception, it is considered to have authorized the transaction. Though there
+are many scripting languages which target Cardano, fundamentally there are only
+two types of script credentials: native scripts and Plutus scripts. Native
+scripts are able to enforce simple rules such as requiring signatures,
+enforcing time limits, and conjunctive and disjunctive combinations thereof,
+i.e. "all of" and "any of" combinations, respectively. Plutus scripts are
+programs compiled to Untyped Plutus Core, a low-level variant of lambda
+calculus which serves as a compilation target for other higher level scripting
+languages such as PlutusTx or Aiken.
+
+As an example, a script can be used to control how a UTxO is spent. The UTxO
+is held by an address containing the script's payment credential, which is a
+cryptographic hash of the script's serialized representation. It is also held
+alongside a piece of data which can be used to represent the "state" of the
+script. To spend the UTxO, the spending transaction must include the actual
+script bytes, either directly or via a reference to a script stored elsewhere
+on chain. The transaction can also provide an argument to the script, called a
+*redeemer*. The script is then executed with the datum held in the UTxO, the
+redeemer provided in the spending transaction, and a summary of the spending
+transaction, called the *script context*. If it executes without raising an
+exception, the UTxO is authorized for being spent.
+
+Script credentials offer many benefits over public key credentials:
+
+* They can encode arbitrarily sophisticated security requirements, such as
+  requiring multiple signatures, limiting the amount of an asset that is
+  withdrawn, enforcing time limits, and much more.
+* Via the datum, they can be associated with supplemental information, which
+  can be used for identity verification.
+* They can have failsafe options built into them to allow recovery of the credential
+  if auxillary data such as private keys are compromised.
+
+However, they also have several disadvantages:
+
+* They are complicated and expensive to create and used compared with public
+  key credentials.
+* If they are not carefully written and tested, there can be unintended edge
+  cases or bugs which compromise their security.
+* Between the script bytes, the datum and the redeemer, they consume a lot of
+  space in transactions, and are expensive to validate compared with public
+  keys and signatures. This makes them more expensive, as these factors
+  increase transaction fees.
+
+Ultimately, script credentials can solve many of the shortcomings of public key
+credentials, but they do so at a cost. They can require significant upfront
+investment to create, especially if they are used for high-risk applications,
+which they often are. They are also expensive to operate, requiring both higher
+transaction fees and an operator with significant technical knowledge (either a
+trained staff member or a commercial service provider which may charge
+additional fees).

docs/_sources/background/index.rst.txt

@@ -0,0 +1,9 @@
+Background Information
+======================
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   credentials
+   cc-credentials

docs/_sources/index.rst.txt

@@ -0,0 +1,25 @@
+Constitutional Committee Credential Management System user guide
+================================================================
+
+Introduction
+------------
+
+The Constitutional Committee Credential Management System is a suite of Plutus
+scripts and tools for managing Cardano constitutional committee credentials
+with an X.509 certificate chain. It provides the following features:
+
+* Separation of capabilities between user roles
+* Multi-signature authorization of on-chain governance transactions
+* Key rotation without modifying registered committee credentials
+* Publicly verifiable authorization of on-chain activity via certificates
+
+This documentation site includes an overview of the system, a user manual for
+each of the end-user roles, and a reference manual that documents every option
+for every tool.
+
+.. toctree::
+   :maxdepth: 1
+
+   background/index.rst
+   system-overview/index.rst
+   orchestrator-cli/index

docs/_sources/orchestrator-cli/index.rst.txt

@@ -0,0 +1,31 @@
+.. _orchestrator_cli:
+
+Orchestrator CLI
+================
+
+The orchestrator CLI is a command-line tool for the orchestrator to use to
+help them prepare transactions with Cardano CLI. It includes commands which
+prepare the various script assets that need to be included in transactions to
+operate the system. It is designed to work alongside Cardano CLI, does not
+require an internet connection, and does not have any environment dependencies.
+As such, it is extremely flexible, designed to adapt to the workflow of the
+user instead of imposing one.
+
+This user guide will walk through building each transaction type with CLI
+tools in an approximate sequence.
+
+.. toctree::
+   :maxdepth: 1
+   :titlesonly:
+
+   init-cold-committee
+   init-cold-nft
+   init-hot-committee
+   init-hot-nft
+   vote
+   resign-delegation
+   resign-voting
+   rotate-cold
+   rotate-hot
+   resign
+   unlock