witness improvements.

[imaginator]

• Add a "Visual Workflow" Diagram: A small mermaid.js or SVG flowchart showing how a developer moves from code to a witness.
• Type Reference Table: Perhaps include a small markdown table of common types (e.g., u8, u32, u256, Signature, Pubkey) and their expected string formats.
• Links to the mentioned example files (htlc.simf, escrow_with_delay.simf) are missing
• provide a link to a JSON schema for .wit files to allow developers to use IDE validation while writing them.

[schoen]

I added the type reference table (and examples!) and the links to the example files, as well as some more explanations of various things.

As far as the JSON Schema, I attempted to write one but this has turned out to be kind of complicated. In particular, the validity conditions for a .wit file are based on validating the type property of each entry. Unfortunately, it is always expressed as a string. Even more unfortunately, because the type definitions are recursive, with arbitrary nesting, JSON Schema literally cannot express their validity conditions (this is like the famous "You can't parse HTML with regular expressions" meme).

We can express their validity conditions (in fact, simc already does so very easily), just not with regular expressions and therefore not with JSON Schema.

I was able to write a .wit value and type annotation validator quickly using a Python library called Lark (which is more powerful than regular expressions in a computer science sense). It works correctly, and can be used in conjunction with my JSON Schema schema to validate the overall syntax of a .wit file and the validity of its type entries (and we can optionally validate the value entries too, although we can't typecheck them against the type entries).

This isn't a trivial issue, in my opinion, because some of the example contracts already use some nested types in their witnesses (so it's not just a theoretical SimplicityHL feature, but a somewhat practical one!). For example, existing example contracts provide witness values of complex types such as Either<[Option<Signature>; 3], Signature>, Either<(u256, Signature), Signature>, Either<Signature, Either<Signature, Signature>>, [Option<Signature>; 3], and Either<Signature, Signature>. Because the Either<> declaration is almost the only way to tell a Simplicity contract what action you want to take, it's probably going to get used a ton in real applications, including with nesting when there are more than two available actions. It's almost like our equivalent of function calls (!) from the point of view of a wallet or app.

Although the options contract doesn't explicitly write a full .wit file to disk (see https://github.com/BlockstreamResearch/simplicity-contracts/blob/main/crates/contracts/src/finance/options/build_witness.rs), if it did, the overall type signature would start Either<Either<Either<..., and the resulting branches would contain between three and nine (!) integer values each. (It might be for the best that we're not trying to actually manipulate such complex witness files in JSON format...)

So I think the basic question is "what kind of validation tools for .wit files would we like to provide, and is it OK if some of them, for example, require Python?", because it appears conceptually impossible to do it with JSON Schema alone.

We could also "just" tell people to run simc on their .wit files, although currently some of the error messages aren't that helpful. We can also add a --validate-witness command to simc to make it check witness file structure even apart from a specific .simf program. This might be nicer than having a method that requires an extra dependency.

[imaginator]

If providing a JSON Schema is tricky then we just drop it for the moment - we have more pressing things.

[imaginator]

• please refer to https://docs.google.com/document/d/1Y8K606oBo43kLP2C5n5Pe1eAfhzWk_r8B63xK4BTPwU/edit?tab=t.0 and https://github.com/BlockstreamResearch/simplicity-lang-org/blob/main/.github/copilot-instructions.md#writing-style for tone. I suggest you run this through AI to check for areas where it's not matching the blockstream voice guidelines. Avoid phrases like yep_nope.

• The document seems very long winded. I would be asking myself "what does the developer what from this" and succinctly writing that up at the start of the document? IMHO the document could be:

• brief intro (see below)

• building signatures with hal-simplicity/simc

• building signatures in rust with a code example

• a single table of witness data types and

• ONE json example that includes one of each (annotate if necessary)

For example they need a description of what a witness is.

The intro is currently long and rambling:

The execution model for Simplicity glossary:contracts allows the user who
is proposing a glossary:transaction to provide input values to the contract. The meaning of these inputs is specific to an individual contract, but in general they help the contract to confirm that the proposed transaction is authorized according to the contract's rules. This is necessary because anyone can propose transactions to spend assets at any time, so a contract needs a clear way to distinguish which transactions are appropriate and which aren't.

The combination of inputs provided as part of a transaction is known as the witness. This term is adopted from its existing use in other kinds of Bitcoin transactions, and originally from a related meaning in computer science.

Among other things, a witness will usually contain digital signatures from some party or parties approving the proposed transaction. It might also include things like

• amounts (for example, how much of an asset is requested to be spent or transferred)
• oracle statements (confirming some fact about the outside world)
• values representing choices among several actions that can be taken at a certain moment (for example, whether a payment should proceed or be cancelled and refunded).

The witness is directly attached to the transaction and forms a part of it; if the transaction is confirmed, the witness data will be publicly visible on the blockchain as part of the confirmed transaction.

In an end-user application, witness data will typically be built by wallet or app software that understands how to interact with a certain contract on the user's behalf. During the contract development process, developers might build it manually.

The rest of this document provides details about the means of creating witnesses and about the kinds of data that can be included inside them. Please note that this document is discussing "inputs" informally in the typical software development sense of data provided to a function or program, not the blockchain-specific sense of the specific glossary:UTXOs consumed by a transaction (which will also be details relevant to many contracts' logic).

Please be more concise with your writing. Something like:

Definition: The Witness In Simplicity, the witness is the set of user-provided arguments required to satisfy a contract's execution logic. It serves as the authorization mechanism, ensuring only valid state transitions occur in a permissionless environment.

• Composition: Common elements include cryptographic signatures, asset amounts, oracle attestations, and control flow selectors (e.g., choosing a "refund" branch).
• Visibility: Witness data is attached to the transaction and permanently recorded on the public blockchain.
• Construction: Generated automatically by wallet software for end-users, or constructed manually by developers during testing.

Things like this are not necessary and could simply be "The .wit file is formatted as a JSON file." (It's JSON" and we are not in the business of describing key-value details):

The .wit file is formatted as a JSON file. Each top-level entry in the file has a name which has two elements: value and type. The entry name is used in the SimplicityHL program as a variable name to refer to this specific entry. The value and type are both strings containing Rust-like code for the data value and data type annotation for the entry. For example,

More built-in types - why is this tacked on at the end rather than included?

[imaginator]

Please don't include things like this "future" "may" - it sounds very indefinite. Just leave it out.

"A future version of simc may be able to automatically generate an associated .wit file from a .simf source file by using the variable names and type annotations present in the source code. Currently, .wit files need to be written manually. You can use the details above to create them or follow examples of witness files corresponding to sample contracts in SimplicityHL/examples."