Warp SDK

⚠️ Following library has been renamed from redstone-smartweave to warp-contracts from version 1.0.0! If you are using older version please read README-LEGACY.

Warp SDK is the implementation of the SmartWeave Protocol.

It works in both web and Node.js environment (requires Node.js 16.5+).

If you are interested in the main assumptions for Warp ecosystem as well as its key features go visit our website.

⚠️ Do not use "Map" objects in the state of js/ts contracts - since maps by default are not serializable to JSON and won't be properly stored by the caching mechanism. Use "plain" objects instead. More info - the "Serialization and parsing" row.

• Development
  • Installation
    • Using npm
    • Using yarn
  • Import
  • WarpFactory
    • forLocal
    • forTestnet
    • forMainnet
    • custom
    • WarpEnvironment
  • Deployment
  • Contract methods
    • connect
    • setEvaluationOptions
    • readState
    • viewState
    • dryWrite
    • writeInteraction
    • evolve
  • WASM
  • VM2
  • Internal writes
  • UnsafeClient
  • Cache
  • CLI
  • Examples
  • Migrations
    • Old factories to WarpFactory
    • Sqlite to LevelDB
    • Additional changes
• Warp transaction lifecycle

Development

PRs are welcome! :-) Also, feel free to submit issues - with both bugs and feature proposals. In case of creating a PR - please use semantic commit messages.

Installation

SDK requires node.js version 16.5+.

Using npm

npm install warp-contracts

Using yarn

yarn add warp-contracts

Import

You can import the full API or individual modules.

The SDK is available in both the ESM and CJS format - to make it possible for web bundlers (like webpack) to effectively perform tree-shaking.

ESM

import * as WarpSdk from 'warp-contracts';

import { Warp, Contract, ... } from 'warp-contracts'

CJS

const Warp = require('warp-contracts');

const { Warp, Contract, ... } = require('warp-contracts');

Using web bundles

Bundle files are possible to use in web environment only. Use minified version for production. It is possible to use latest or specified version.

<!-- Latest -->
<script src="https://unpkg.com/warp-contracts/bundles/web.bundle.js"></script>

<!-- Latest, minified-->
<script src="https://unpkg.com/warp-contracts/bundles/web.bundle.min.js"></script>

<!-- Specific version -->
<script src="https://unpkg.com/warp-contracts@1.0.0/bundles/web.bundle.js"></script>

<!-- Specific version, minified -->
<script src="https://unpkg.com/warp-contracts@1.0.0/bundles/web.bundle.min.js"></script>

All exports are stored under warp global variable.

<script>
  const warp = warp.WarpFactory.warpGw(arweave);
</script>

WarpFactory

To properly initialize Warp you can use one of three methods available in WarpFactory class which simplifies the process of creating Warp.

forLocal

Creates a Warp instance suitable for testing in a local environment (e.g. with a use of a ArLocal instance).

warp = WarpFactory.forLocal();

Default parameters (each of them can be adjusted to your needs):

1. port - set to 1984
2. arweave - Arweave initialized with host set to localhost, port set to default port from p. 1 and protocol set to http
3. cacheOptions - optional cache options parameter, by default inMemory cache is set to true

forTestnet

Creates a Warp instance suitable for testing with Warp testnet.

warp = WarpFactory.forTestnet();

Default parameters (each of them can be adjusted to your needs):

1. arweave - Arweave initialized with host set to testnet.redstone.tools, port set to 443 and protocol set to https
2. cacheOptions - optional cache options parameter, by default inMemory cache is set to false

forMainnet

Creates a Warp instance suitable for use with mainnet. By default, the Warp gateway is being used for:

1. deploying contracts
2. writing new transactions through Warp Sequencer
3. loading contract interactions

warp = WarpFactory.forMainnet();

Default parameters (each of them can be adjusted to your needs):

1. cacheOptions - optional cache options parameter, by default inMemory cache is set to false
2. useArweaveGw - defaults to false, if set to true - arweave.net gateway is used for deploying contracts, writing and loading interactions
3. arweave - Arweave initialized with host set to arweave.net, port set to 443 and protocol set to https

custom

Allows to fully customize Warp instance.

warp = WarpFactory.custom(
  arweave,
  {
    ...defaultCacheOptions,
    inMemory: true
  },
  'testnet'
)
  .useArweaveGateway()
  .setInteractionsLoader(loader)
  .build();

No default parameters are provided, these are the parameters that you can adjust to your needs:

1. arweave - initializes Arweave
2. cacheOptions - optional cache options parameter
3. environment - environment in which Warp will be initialized

custom method returns preconfigured instance of Warp - WarpBuilder which can be customized, the configuration is finished with build method.

WarpEnvironment

WarpEnvironment is a helper type which can be used in scripts etc. to determine in which environment Warp has been initialized.

Possible options:

'local' | 'testnet' | 'mainnet' | 'custom';

  if (warp.environment == 'mainnet') {
    ...
  }

Deployment

deploy

Deploys contract to Arweave. By default, deployment transaction is bundled and posted on Arweave using Warp Sequencer. If you want to deploy your contract directly to Arweave - disable bundling by setting disableBundling to true.

async function deploy(contractData: ContractData, disableBundling?: boolean): Promise<ContractDeploy>;

Example

const { contractTxId, srcTxId } = await warp.createContract.deploy({
  wallet,
  initState: initialState,
  data: { 'Content-Type': 'text/html', body: '<h1>HELLO WORLD</h1>' },
  src: contractSrc,
  tags
});

deployFromSourceTx

Deploys contract from source transaction. By default deployment transaction is bundled and posted on Arweave using Warp Sequencer. If you want to deploy your contract directly to Arweave - disable bundling by setting disableBundling to true.

async function deployFromSourceTx(
  contractData: FromSrcTxContractData,
  disableBundling?: boolean
): Promise<ContractDeploy>;

Example

const { contractTxId, srcTxId } = await warp.createContract.deployFromSourceTx({
  wallet,
  initState: initialState,
  srcTxId: 'SRC_TX_ID'
});

Contract methods

connect

connect(signer: ArWallet | SigningFunction): Contract<State>;

Allows to connect wallet to a contract. Connecting a wallet MAY be done before "viewState" (depending on contract implementation, ie. whether called contract's function required "caller" info) Connecting a wallet MUST be done before "writeInteraction".

• signer - JWK object with private key, 'use_wallet' string or custom signing function.

Example

const contract = warp.contract('YOUR_CONTRACT_TX_ID').connect(jwk);

---

setEvaluationOptions

function setEvaluationOptions(options: Partial<EvaluationOptions>): Contract<State>;

Allows to set EvaluationOptions that will overwrite current configuration.

Example

const contract = warp.contract('YOUR_CONTRACT_TX_ID').setEvaluationOptions({
  waitForConfirmation: true,
  ignoreExceptions: false
});

---

readState

import { SortKeyCacheResult } from './SortKeyCache';

async function readState(
  sortKeyOrBlockHeight?: string | number,
  currentTx?: { contractTxId: string; interactionTxId: string }[]
): Promise<SortKeyCacheResult<EvalStateResult<State>>>;

Returns state of the contract at required blockHeight or sortKey. Similar to the readContract from the version 1.

• sortKeyOrBlockHeight - either a sortKey or block height at which the contract should be read
• currentTx - if specified, will be used as a current transaction

Example

const { sortKey, cachedValue } = await contract.readState();

---

viewState

async function viewState<Input, View>(
  input: Input,
  blockHeight?: number,
  tags?: Tags,
  transfer?: ArTransfer
): Promise<InteractionResult<State, View>>;

Returns the "view" of the state, computed by the SWC - ie. object that is a derivative of a current state and some specific smart contract business logic. Similar to the interactRead from the current SDK version.

• input the interaction input
• blockHeight if specified the contract will be replayed only to this block height
• tags an array of tags with name/value as objects
• transfer target and winstonQty for transfer

Example

const { result } = await contract.viewState<any, any>({
  function: "NAME_OF_YOUR_FUNCTION",
  data: { ... }
});

---

dryWrite

async function dryWrite<Input>(
  input: Input,
  caller?: string,
  tags?: Tags,
  transfer?: ArTransfer
): Promise<InteractionResult<State, unknown>>;

A dry-write operation on contract. It first loads the contract's state and then creates a "dummy" transaction and applies the given Input on top of the current contract's state.

• input - input to be applied on the current contract's state
• tags - additional tags to be added to interaction transaction
• transfer - additional transfer data to be associated with the "dummy" transaction
• caller - an option to override the caller - if available, this value will overwrite the caller evaluated from the wallet connected to this contract.

Example

const result = await contract.dryWrite({
  function: "NAME_OF_YOUR_FUNCTION",
  data: { ... }
});

---

writeInteraction

async function writeInteraction<Input = unknown>(
  input: Input,
  options?: WriteInteractionOptions
): Promise<WriteInteractionResponse | null>;

Writes a new "interaction" transaction - i.e. such transaction that stores input for the contract.

• input the interaction input
• options - an object with some custom options (see WriteInteractionOptions)

By default write interaction transactions are bundled and posted on Arweave using Warp Sequencer. If you want to post transactions directly to Arweave - disable bundling by setting options.disableBundling to true.

Example

const result = await contract.writeInteraction({
  function: "NAME_OF_YOUR_FUNCTION",
  data: { ... }
});

---

evolve

async function evolve(newSrcTxId: string, options?: WriteInteractionOptions): Promise<WriteInteractionResponse | null>;

Allows to change contract's source code, without having to deploy a new contract. This method effectively evolves the contract to the source. This requires the save method to be called first and its transaction to be confirmed by the network.

• newSrcTxId - result of the save method call.
• options - an object with some custom options (see WriteInteractionOptions)

By default evolve interaction transactions are bundled and posted on Arweave using Warp Sequencer. If you want to post transactions directly to Arweave - disable bundling by setting options.disableBundling to true.

Example

const result = await contract.evolve('srcTxId');

save

Allows to save contract source on Arweave. Currently, using bundler to save the source is not possible.

async function save(
  contractSource: SourceData,
  signer?: ArWallet | SigningFunction,
  useBundler?: boolean
): Promise<string | null>;

Example

const newSrcTxId = await contract.save({ src: newSource });

WASM

WASM provides proper sandboxing ensuring execution environment isolation which guarantees security to the contracts execution. As for now - Assemblyscript, Rust and Go languages are supported. WASM contracts templates containing example PST contract implementation within tools for compiling contracts to WASM, testing, deploying (locally, on testnet and mainnet) and writing interactions are available in a dedicated repository.

Using SDKs' methods works exactly the same as in case of a regular JS contract.

Additionally, it is possible to set gas limit for interaction execution in order to e.g. protect a contract against infinite loops. Defaults to Number.MAX_SAFE_INTEGER (2^53 - 1).

contract = smartweave.contract(contractTxId).setEvaluationOptions({
  gasLimit: 14000000
});

VM2

It is possible to provide an isolated execution environment also in the JavaScript implementation thanks to VM2 - a sandbox that can run untrusted code with whitelisted Node's built-in modules. It works only in a NodeJS environment and it enhances security at a (slight) cost of performance, so it should be used it for contracts one cannot trust.

In order to use VM2, set useVM2 evaluation option to true (defaults to false).

contract = warp.contract(contractTxId).setEvaluationOptions({
  useVM2: true
});

Internal writes

SmartWeave protocol currently natively does not support writes between contract - contracts can only read each others' state. This lack of interoperability is a big limitation for real-life applications - especially if you want to implement features like staking/vesting, disputes - or even a standard approve/transferFrom flow from ERC-20 tokens.

SmartWeave protocol has been extended in Warp by adding internal writes feature.

A new method has been added to SmartWeave global object. It allows to perform writes on other contracts.

const result = await SmartWeave.contracts.write(contractTxId, { function: 'add' });

The result of the internal write contains the result type (ok, error, exception) and the most current state of the callee contract (i.e. after performing a write). If the function called by the SmartWeave.contracts.write throws an error, the parent transaction throws a ContractError by default - so there is no need to manually check the result of the internal write.

In order for internal calls to work you need to set evaluationOptions to true:

const callingContract = smartweave
  .contract<ExampleContractState>(calleeTxId)
  .setEvaluationOptions({
    internalWrites: true
  })
  .connect(wallet);

A more detailed description of internal writes feature is available here.
A list of real life examples are available here.

You can also perform internal read to the contract (originally introduced by the protocol):

await SmartWeave.contracts.readContractState(action.input.contractId);

unsafeClient

unsafeClient is available to use on Smartweave global object. It gives access to whole Arweave instance. Example of usage:

const result = await SmartWeave.unsafeClient.transactions.getData('some_id);

However, we do not recommend using it as it can lead to non-deterministic results. Therefore, we do not support it by default in Warp. If you want to use it anyway, you need to explicitely set EvaluationOptions.allowUnsafeClient flag to true.

Cache

Warp uses LevelDB to cache the state. During the state evaluation, state is then evaluated only for the interactions that the state hasn't been evaluated yet. State is being cached per transaction and not per block height. The reason behind that caching per block height is not enough if multiple interactions are at the same height and two contracts interact with each other. The LevelDB is a lexicographically sorted key-value database - so it's ideal for this use case - as it simplifies cache look-ups (e.g. lastly stored value or value "lower-or-equal" than given sortKey). The cache for contracts are implemented as sub-levels. The default location for the node.js cache is ./cache/warp.

In the browser environment Warp uses IndexedDB to cache the state - it's a low-level API for client-side storage. The default name for the browser IndexedDB cache is warp-cache.

In order to reduce the cache size, the oldest entries are automatically pruned.

It is possible to use the in-memory cache instead by setting cacheOptions.inMemory to true while initializing Warp. inMemory cache is used by default in local environment.

CLI

A dedicated CLI which eases the process of using main methods of the Warp SDK library has been created. Please refer to warp-contracts-cli npm page for more details.

Migrations

old factories to WarpFactory

1. Mainnet
   This is how you would intiialize Warp 'the old way':

const warp = WarpNodeFactory.memCachedBased(arweave).build();

or - for browser:

const warp = WarpNodeFactory.memCachedBased(arweave).build();

Now, you just need to initialize it like so:

const warp = WarpFactory.forMainnet();

If you want to use Arweave gateway instead of default Warp gateway, go with a custom configuration:

const warp = WarpFactory.custom(
  arweave,
  {
    ...defaultCacheOptions
  },
  'mainnet'
)
  .useArweaveGateway()
  .build();

2. RedStone public testnet

Previously, you would intialize Warp in testnet environment exactly like you would initialize Warp in mainnet, you would just need to set correct Arweave instance. Now the process is simplified:

warp = WarpFactory.forTestnet();

3. ArLocal

This is how you would intialize it previously:

warp = WarpNodeFactory.forTesting(arweave);

Now:

warp = WarpFactory.forLocal();

Remember that you are always allowed to initialize Warp depending on your needs by using custom factory method.

sqlite to levelDB

If you've been using Knex based cache you can now easily migrate your sqlite database to levelDB. Just use our migration tool, set correct path to your sqlite database in this line:

const result = await warp.migrationTool.migrateSqlite('./tools/sqlite/contracts-3008.sqlite');

...and run the script:

yarn ts-node -r tsconfig-paths/register tools/migrate.ts

Additional changes

1. the type of the result of the readState has changed: https://github.com/warp-contracts/warp#readstate

2. the bundleInteraction method has been removed. The SDK now decides automatically how the transaction should be posted (based on the environment - i.e. whether the warp instance has been created for mainnet, testnet or local env).

3. the internalWrite, if the write itself fails, now throws the ContractError by default. There's no longer need to manually check the result of the write inside the contract code (and throw error manually if result.type != 'ok'). If you want to leave the check in the contract code - set the

.setEvaluationOptions({
  throwOnInternalWriteError: true
});

4. The warp instance now contains info about the environment - https://github.com/warp-contracts/warp#warpenvironment . This might be useful for writing deployment scripts, etc.
5. if the warp instance was obtained via WarpFactor.forLocal (which should be used for local testing with ArLocal), then:

• you can use warp.generateWallet() for generating the wallet - it returns both the jwk and wallet address - example.
• you can use warp.testing.mineBlock() to manually mine ArLocal blocks
• the ArLocal blocks are mined automatically after calling .writeInteraction. This can be switched off by setting evaluationOptions.mineArLocalBlocks to false - example.

Examples

We've created an academy that introduces to the process of writing your own SmartWeave contract from scratch and describes how to interact with it using Warp SDK.

The example usages with different web bundlers and in Node.js env are available here.

A community package - arweave-jest-fuzzing has been released thanks to Hansa Network to help SmartWeave developers write fuzzy tests.

Bundled interactions and bundled deployment

Warp gateway bundles transactions underneath. Please refer to Bundled contract and Bundled interaction docs to read the specification.

Warp transaction lifecycle

Warp SDK is just part of the whole Warp smart contracts platform. It makes transactions processing and evaluation easy and effective.

1. Our Sequencer assigns order to SmartWeave interactions, taking into account sequencer’s timestamp, current Arweave network block height and is salted with sequencer’s key.

2. Interactions are then packed by Bundlr which guarantees transactions finality and data upload reliability. The ability to directly process rich content

3. Transactions are stored on Arweave where they are available for querying.

4. The key component for the lazy-evaluation nature of SmartWeave protocol is fast and reliable interaction loading. Thanks to our gateway we guarantee loading transactions in seconds in a reliable way - it has built-in protection against forks and corrupted transactions. Our gateway enables fast queries and efficient filtering of interactions, which in effect greatly reduces state evaluation time.

5. Lastly, transactions can be evaluated either by our SDK or the evaluation can be delegated to a distribution execution network - a dedicated network of nodes (DEN). Multi-node executors network listens to incoming transactions and automatically update contract state.