Ledger CIP for documenting witnesses

[Ryun1]

Currently there is no documentation, beyond code and formal spec, on what witnesses the ledger requires per transaction contents. Personally I struggle to read both of these so had partly documented this via Certificate and transaction field witnesses and deposits, but this site is likely to be closed at some point.

With the Conway era introducing many new transaction body fields and certificate types this has been caused some confusion and frustration.

For most fields in a transaction, it can be obvious, but some older certificates can be confusing to deal with.

I believe a CIP documenting the required credential witnesses for each inclusion within a transaction body, would be a nice to have for builders. Maybe also include explanation of deposits and refunds.

Is CIPs a suitable place for this? or would another documentation site be more suitable?

[rphair]

@Ryun1 I think a CIP will be a much more accessible place than item # 4 (currently) on a little known web page on a testnet web site. It would have just as much place in the CIP repository as the enumerations of key names & prefixes, derivation paths, and other technical documentation like we have had from the beginning.

The one alternative I know would be on the Developer Portal (in 2024 we were talking about renaming this; though that effort seems to be going slowly & I don't know if that's still planned anymore, cc @katomm) perhaps in the Getting Started section... considering that the node installation instructions, tracing system, and more node/CLI documentation has been provided & updated recently by @CarlosLopezDeLara @crocodile-dentist @coot @Icelandjack.

I guess either of those 2 choices would be acceptable... and perhaps should be chosen by whomever is most likely to maintain the document. The Ledger team itself has not, to my knowledge, contributed to the Dev Portal (cc @WhatisRT @lehins) though ever since @JaredCorduan's time they have always filled out the CIP repository with information both documenting the past & anticipating the future.

By elimination then I suppose posting a CIP with what you have written so far is the way to go, and if my reasoning is valid then we can expect the Ledger reps to monitor & perhaps maintain it. To cover both bases, when the CIP is ready we could also submit a PR on the developer portal somehow working the witness table into the Getting Started docs.