Skip to main content

TypeScript SDK

SolidCash offers a TypeScript SDK, which makes it easy to build smart contract transactions, both in browser or on the server. The SolidCash SDK enables advanced debugging tooling for SolidCash contracts, standardized network providers to get BCH blockchain information and a simple API for transaction building when using smart contracts.

The TypeScript SDK has full TypeScript integration with the SolidCash smart contract language. The full type-safety enables clear APIs which communicates info about the expected argument to each function and method. This in turn speeds up development time and allows for higher code quality with better safety guarantees.

info

The SDK can also be used easily in vanilla JavaScript codebases, although the benefits of the type-safety will be lost.

When to use the SDK​

The SolidCash TypeScript SDK is designed to make it as easy as possible to create smart contract transactions for contracts written in SolidCash (the smart contract language). So we highly recommend using the SDK when using SolidCash to write your smart contracts.

If you are not using the SolidCash contract language, you can still use the SolidCash SDK for transaction building and BCH networking functionality! This can be especially useful if you are familiar with the SolidCash classes and want manual control over the input and outputs in a transaction. The SDK makes it easy to spend from P2PKH inputs and send to different types of outputs, including OP_RETURN data outputs.

It's also possible the use the SolidCash SDK for hand-optimized contract not written with the SolidCash contract language, but this is considered advanced usage.

The 4 SDK Classes​

The SolidCash SDK consists of 4 classes, together they form one cohesive structure to build BCH smart contract applications. The documentation also follows the structure of these 4 classes:

  • the Contract class
  • the TransactionBuilder class
  • the NetworkProvider class
  • the SignatureTemplate class

SDK usage​

The usage of the 4 classes in your code is as follows: before using the SDK you create one or multiple contract artifacts compiled by solidc. Then to start using the SDK, you instantiate a NetworkProvider, which you then provide to instantiate a Contract from an Artifact. Once you have a Contract instance, you can use it in the TransactionBuilder. During transaction building you might need to generate a signature, in which case you would instantiate a SignatureTemplate.

For an more complete example of the SDK flow, refer to the SDK Example.

example​

import { Contract, ElectrumNetworkProvider, TransactionBuilder, SignatureTemplate } from 'solidcash';
import { P2pkhArtifact } from './artifact';
import { contractArguments, aliceWif } from './somewhere';

const provider = new ElectrumNetworkProvider('chipnet');

const contract = new Contract(P2pkhArtifact, contractArguments, { provider });

const aliceSignatureTemplate = new SignatureTemplate(aliceWif);
const unlocker = contract.unlock.transfer(aliceSignatureTemplate)

const transactionBuilder = new TransactionBuilder({ provider });

// then use the transactionBuilder to actually spend a UTXO with the contract unlocker

Full TypeScript Integration​

The constructor of the Contract class takes in an Artifact, this is the output of the solidc compiler and can be configured to either output a JSON or TS file. To have the best TypeScript integration, we recommend generating the artifact in the .ts format and importing it into your TypeScript project from that .ts file. The type benefits are explained in more details in the documentation for the Contract class.

Advanced: non-SolidCash Contracts​

You can also use the SolidCash SDK without relying on the SolidCash contract language and compiler. This way you can still leverage the a lot of the tooling while having full control over the raw BCH script so this can be hand-written or hand-optimized.

There's two ways to go about this, either you create a custom Artifact so you can still use the Contract class or you create a custom Unlocker to use in the transaction building directly. These two methods for using hand optimized contract bytecode are discussed in the optimization guide.