cashconnect-js

High Level Flow

sequenceDiagram
    Dapp (Frontend)->>+Wallet: Send Template/Session Parameters
    Note over Dapp (Frontend),Wallet: Assuming WC-like Transport here where there's a session.<br/>But HTTP-like transport would be similar...<br/>it would just include template/executeAction in single call instead.
    Wallet->>+Wallet: User Views/Approves
    Wallet->>Dapp (Frontend): Return Session Details
    Dapp (Frontend)->>+Wallet: executeAction(someAction, params)
    Note over Dapp (Frontend),Wallet: executeAction on the Dapp-end behaves like a proxy<br/>It simply forwards the action/params to the Wallet to execute.
    Wallet->>+Wallet: executeAction is executed internally with the given Parameters
    Wallet-->>+Wallet: XO Wallet, specifically, would be smart about this and store params, outputs, etc.<br/> (But this is not compulsory for other wallets)
    Wallet->>Dapp (Frontend): Result of action (data) execution is sent back to Dapp.

Dapp Integration

TODO: Link to Docs

Wallet Integration

TODO: Link to Cashonize

Current Limitations/Caveats

• Objects use __ as separator as opposed to . character.

  CashASM variables cannot contain . characters (these would conflict with private key operations in CashASM). When you pass an object to templates, paths are delimited by a __ (double-underscore) seperator instead. Note that the expr util in the template-dev package will automatically replace . characters with __ characters, but if you are using raw CashASM, you will need to use __ in place of ..

• Script resolutions are only single-level depth (as opposed to deeply nested).

  Though I don't think this pattern will be common, it might cause problems for some contracts that deeply nest lockscript precommits that need different values for same-named variables, but is difficult to work-around. CashASM assumes variables are flattened and, therefore, you will not be able to use the same variable name twice with different values within the one script. My original approach to try to work around this was to recursively resolve the actual values of each nested script (worked fine for lockingBytecode), but I was unable to get this working for unlockingBytecode (it might be possible, but I haven't worked out an elegant approach yet).

  The new approach (which only allows single-level-nesting) just sets the scripts that are to be resolved as actual scripts. This is cleaner code, but has the above limitation.

  If you have contracts that do this, you might need to ensure that each variable is uniquely named.

Roadmap

• Separate Templates into stand-alone package (distinct from CashConnect Transport)

• Formalize State Handling into Template Schema via consumes field on each Action.

  • Add support for Outpoint type (concatenation of OutpointHash and OutpointIndex)
  • State Machine Store/Model for easy data persistence
  • Tooling to generate state-machine diagrams

  Note: This would likely make it so that additional unlock params (e.g. oracleMessage and oracleSignature) would be separate. In this sense, it would be like we have:

  1. Params (e.g. params.oracleMessage)
  2. States (e.g. states.match)

  This might get a little bit messy on the stack, so we want to make sure that we don't hurt DX too much in doing this.

• Introspective State Inference (complex - don't know how this should look exactly yet)

• Templated Wallet examples

• HTTP Transport (BIP70-like)

• LibP2P Transport (hopefully to replace WalletConnect)

• Default Dapp Packages

  • Vanilla HTML/JS package for standard Dapp integration
  • Console-based package for testing