FAQ
What is the difference between this and other BCH templating systems?
I think this is a relatively different take on it: Most others I've seen attempt to formalize the schema; whereas, I've treated them as instruction pipelines as it gives us versatility, extendability and simplicity (in terms of implementation complexity).
That said, the template schema I have is largely inspired by LibAuth. The concept of actions aren't too dissimilar in concept to LibAuth scenarios. But, while scenarios are (currently) limited to single Transactions, this schema behaves more like a pipeline of different constructs/operations (currently: resolve and transaction).
It's quite possible that this template design will be superceded by LibAuth itself. My objective here was to get something relatively powerful out in the short-term that can help inform other future Templating Systems through practical experimentation.
Why a pipeline/instructions approach?
In short, it's very versatile and easily extendable. Originally, I had tried different approaches to formalize the Template structure, but always encountered gaps with specific use-cases. By, instead, treating it in a similar manner as we would a SQL/NoSQL-esque pipeline grants us a lot of flexibility to accommodate for weird flows and unusual contract-systems. Templates then become like an API that Dapps are able to invoke (actions are conceptually like functions that you'd invoke with any other API - they follow the IPO "inputs, processes and outputs" pattern).
In addition, the logic to implement it is also relatively straight-forward, meaning it should not be too difficult to port to other languages (e.g. Python and C++), whereas a schema with many behavioural assertions to accommodate different use-cases can become quite complex to implement (and, often, use as well).
Are there any alternatives implementations you considered?
Yes, several. Most suffered from the same versatility problem mentioned above. That said, there was one approach which I think might have legs and might be more fluent than what I have here.
Instead of a pipeline of instructions, we use a CashScript-like language to set variables and transaction properties. For example:
// Set vars a and b.
amount = 5000;
fee = 1000;
// Set the value Satoshis
transactions[0].outputs[0].valueSatoshis = amount + fee;
// Return some variables.
returns.someVariable = 'someValue';However, this would've been very high-effort to explore at the time as it would've required a custom CashScript-like compiler and custom CashASM operations. It's something I'd like to explore in future though (or hope someone else might) as I do think it might be a superior approach.
Why not just write the templates in JSON?
There are a few reasons for this:
- By shunting complexity to the tooling, we minimize implementation complexity (meaning the core implementation becomes easier to maintain and port to other languages).
- Complex Contract Systems would be too difficult to audit if they were a single JSON file. By instead compiling down to JSON, developers can better break their code down (e.g. a file per action, files per states, etc), making it easier to comprehend by auditors.
- Some contract-systems may benefit from being able to build custom tooling to simplify their templates (many contact-systems might actually do this).
- Many Contract Systems will be using CashScript which requires a build-step anyway (so it pays to just streamline this into the CashConnect tooling).
- CashASM would be difficult for most auditors to read. Being able to use a CashScript-esque language probably more naturally for most developers.
The trade-off with the above is that templates become larger due to the repetition. However, much of this size is in the states (params and returns) which will likely have their own property in the schema eventually (I'm just being cautious about adding it prematurely to ensure that we formalize it in a way that doesn't hinder versatility).
NOTE: In practice, it might be that all re-usable components are grouped under one property - so that might include Instructions.
How will auditing templates work?
The idea here is that because templates are JSON, they can be hashed and signed by trusted parties. The specific approach I'm planning for this is as follows:
- Wallets will come stocked with a predefined whitelist of Trusted Public Keys (and, ideally allow adding third-party public keys for advanced users)
- Audits from each public key will be stored on-chain (see Onchain Storage Template Example which stashes data in an input - unlike OP_RETURN, this cannot be spammed by unauthenticated parties).
- This allows wallets to then fetch a list of Audits by simply fetching data on the address that corresponds to the Public Key.
I'll be building a Dapp to ease management of the above. There will also be a Storage Adapter to help with parsing/syncing the audit information (and any other information/protocols that are built upon the concept).
Why must all params and returns be provided as Uint8Arrays?
In short, it's because this is how things are treated, under the hood, in CashASM/BitcoinCash VM. That said, I will be adding support for other types to make usage more convenient/fluent.
This isn't necessarily a straightforward thing though as it's debatable which types should actually be supported. For the JS/TS implementation, it probably makes sense to just support JS-native types (e.g. Uint8Array, string, bigint, etc) and cast to/from Uint8Array, but we also need an outpoint type that gets special treatment (when executing an Action, UTXOs should be fetched prior to any instruction execution).
Can I use templates for building custom Wallet Types?
Yes, but you'll want to wait for V1 release: There are some important features missing (e.g. array handling for multiple recipients and HD Keys).
I'll document how to do this post-V1, but I think it is a relatively clean approach (the gist of it is that "Wallets/Vaults" just become a standardized Action API).
Can I use these templates on the backend of my Dapps?
To some degree, yes. But, right now, it's a bit limited in usefulness as state inference isn't currently supported.
State Inference will be added when support the outpoint type on params/returns. The idea is that outpoints then become a param and are fetched prior to pipeline execution. In doing this, we can then get introspection-like capabilities and actions can be created to infer states when an outpoint is spent.
I'll go into a bit more detail on this later on, but I think it's a relatively decent approach that shouldn't really require any new instruction types.
I have useful Templates/Utils/Tooling - should I suggest these for your templates-dev repository?
Yes please! The utils I have at the moment are very minimal. But, I definitely want to look at making Template Creation more convenient and easier to audit (the more readable we can make it, the better).
For example, the following are on the TODO list for implementation:
// Create a consolidation transaction.
Instructions.consolidationTransaction(...);
// Create token genesis transactions.
Instructions.tokenGenesisTransactions(count: number);I'd also like to create a InstructionsBuilder-like class that gives a more Object-Oriented feel to template creation (e.g. like a TxBuilder). This is a bit harder to scope though, so I've begun with functional utilities for now.
Can I use the utils (e.g. Primitives, Wallets, Blockchain) for other BCH apps?
You can - but I wouldn't yet as it's not stable nor well-tested.
This tooling is carried across from another more generalized library I've been working on which I'll release early next year (2026) under a different brand-name. CashConnect tooling will then be converted to leverage this.
Will newer versions still be compatible with older versions (i.e. no breaking changes)?
The intent is yes and it will be following a Semantic Versioning approach.
But, please note we're not at V1 yet, so there will still be breaking changes.