Consider transaction-shape annotations

[mr-zwets]

Multiple people have started to describe their tx-shapes for each function inside the .cash file

an example of this is CashStarter by @SayoshiNakamario : https://github.com/SayoshiNakamario/CashStarter/blob/main/CashStarter.cash

@jimtendo wrote:

But, the way he's laid out Tx Shapes in the .cash files is great. [...] I could see this eventually evolving into a typed system that's somewhat JSDoc/Typedoc-esque. Where I found this becomes a bit tricky is when an Unlock Function might support several different tx shapes (as an example, imagine a game with a "payout" function... there might be cases where there's a clear winner - or there might be a "draw" case that requires a different shape

We'd need to think about what benefits this would offer inside the .cash file and how we'd need to change the artifact if we'd want these benefits to flow through to the SDK.

I'm not sure whether there is any other programming language which has a similar structure, this is very much unique to the UTXO architecture with introspection...

[mr-zwets]

Benefits of these annotations to developers (why we see them being used)

• alias names for all inputs/outputs
• number of inputs/outputs (optional in/outputs, flexibility in tx shape)
• type of input/output (bch/fungible tokens/nft/opreturn)

possible benefits of standardization

• smart contracts look more alike
• define 'best practices'
• SDK can display type check number of in/outputs
• SDK typings could possibly also check type of input/output

difficulties for standardization

• are these defined inside or outside the contract (maybe right before each function?)
• compact notation or elaborate notation?
• how to deal with multiple different tx-shapes for the same function
• how to mark optional in/outputs or how to mark flexibility in all remaining in/outputs after a certain index
• allow for user description for context (comments)?

experimentation examples:

elaborate notation:

/**
 * @txshape pledge
 * @inputs
 * - input0: [NFT] CampaignNFT
 * - input1: [BCH] User UTXO 
 * -  ...
 *
 * @outputs
 * - output0: [NFT] CampaignNFT (required)
 * - output1: [NFT] RefundNFT (required)
 * - output2: [BCH] UserChange (optional)
 */

compact notation:

// function pledge
// Inputs: 00-CampaignNFT, 01-UserUTXO
// Outputs: 00-CampaignNFT, 01-RefundNFT, 02?-BCH-change