Awesome

TestWeave SDK

This is the SDK of the TestWeave. TestWeave is the testing environment of the Arweave.

MANDATORY PREREQUISITES

To work with the TestWeave, you need to install a local testnet. To do so, follow the instructions here: https://github.com/ArweaveTeam/testweave-docker

Installation

You can install the SDK by means of NPM, as following:

npm install testweave-sdk

Or you can grab the package directly from the arweave, as following:

npm install https://arweave.net/IkZLzAPt8ArujsQL6Y7Rx1CTZx8N0hgUTLvl5_Uokls

and then import it in your project as the following:

import TestWeave from 'testweave-sdk';

Usage

The SDK supplies handlers for testing the followings:

deploying files on the Arweave;
deploying and testing SmartWeave contracts on the Arweave;

Firstly you need to create a TestWeave instance on the top on an Arweave node, as following:

import TestWeave from 'testweave-sdk';

// init arweave as usual
const arweave = Arweave.init({
  host: 'localhost',
  port: 1984,
  protocol: 'http',
  timeout: 20000,
  logging: false,
});

// init TestWeave on the top of arweave
const testWeave = await TestWeave.init(arweave);

And here you go! Now you can use your arweave instance as usual, but every interaction will be performed on the test network!

For a fast bootstrap checkout the examples in the following sections.

To check all the useful helpers that the SDK supplies, checkout the XXX section.

Example 1 - Submitting a data transaction

Initialize the arweave node and the TestWeave on it:

import Arweave from 'arweave';
import TestWeave from 'testweave-sdk';

const arweave = Arweave.init({
  host: 'localhost',
  port: 1984,
  protocol: 'http',
  timeout: 20000,
  logging: false,
}); 

const testWeave = await TestWeave.init(arweave);

Create a data transaction, sign and post it

const data = `
<html>
  <head>
    <meta charset="UTF-8">
    <title>Info about arweave</title>
  </head>
  <body>
    Arweave is the best web3-related thing out there!!!
  </body>
</html>`
const dataTransaction = await arweave.createTransaction({
  data,
}, testWeave.rootJWK)

await arweave.transactions.sign(dataTransaction, testWeave.rootJWK)
const statusBeforePost = await arweave.transactions.getStatus(dataTransaction.id)
console.log(statusBeforePost); // this will return 404
await arweave.transactions.post(dataTransaction)
const statusAfterPost = await arweave.transactions.getStatus(dataTransaction.id)
console.log(statusAfterPost); // this will return 202

Use the TestWeave to instantly mine the block that contains the transaction

await testWeave.mine();
const statusAfterMine = await arweave.transactions.getStatus(dataTransaction.id)
console.log(statusAfterMine); // this will return 200

Thats it!

Example 2 - Publishing and Interacting with SmartWeave Contracts

Initialize the arweave node and the TestWeave on it:

import Arweave from 'arweave';
import TestWeave from 'testweave-sdk';

const arweave = Arweave.init({
  host: 'localhost',
  port: 1984,
  protocol: 'http',
  timeout: 20000,
  logging: false,
}); 

const testWeave = await TestWeave.init(arweave);

Create a SmartWeave PST contract (you can find a sample contract source and its init state, built on the TestWeave root address, here: https://github.com/ArweaveTeam/testweave-sdk/tree/main/tests/fixtures:

import { createContract, readContract, interactWrite, interactWriteDryRun } from 'smartweave';
import fs from 'fs';

// import the sample contract init state
import contractInitState from 'token-pst-contract.json';
// load the contract as a string
const contractSource = fs.readFileSync('token-pst-contract.js').toString();

// create the contract and mine the transaction for creating it
const c = await createContract(arweave, testWeave.rootJWK, contractSource, JSON.stringify(contractInitState));
await testWeave.mine();

Read the contract state, transfer some token to a generated wallet, and read again the contract state

// read the contract before performing any interaction
const beforeTransaction = await readContract(arweave, c);
console.log(`Before interact write: ${JSON.stringify(beforeTransaction)}`)

// generate a wallet
const jkw = await arweave.wallets.generate();
const generatedAddr = await arweave.wallets.getAddress(jkw)

// interact with the contract
const iwt = await interactWrite(arweave, testWeave.rootJWK, c, {
  function: 'transfer',
  target: generatedAddr,
  qty:5000
}, [] , generatedAddr, '23999392')
console.log(`Interact write transaction: ${JSON.stringify(iwt)}`);

// mine the contract interaction transaction
await testWeave.mine();

// get the new balance of the generated address (it should be 23999392)
const generatedAddressBalance = await arweave.wallets.getBalance(generatedAddr)
console.log(generatedAddressBalance)

// read the contract after the interact write transaction (the generated wallet should own 5000 tokens)
const afterTransaction = await readContract(arweave, c);
console.log(`After interact write: ${JSON.stringify(afterTransaction)}`);

SDK helpers

For easily test Arweave applications, the SDK supplies the helpers described in the following sections.

drop(wallet, quantity)

Drops AR from the root wallet to another one. Use it as followings:

const jkw = await arweave.wallets.generate();
const generatedAddr = await arweave.wallets.getAddress(jkw);
await testWeave.drop(generatedAddr, '10000');
const generatedAddressBalance = await arweave.wallets.getBalance(generatedAddr) // returns 10000

mine()

Mines the following block of the testnet and all the transactions contained in it.

await testWeave.mine();

getter rootJWK

Returns the root JWK, it has an initial balance of 10000000 and the address MlV6DeOtRmakDOf6vgOBlif795tcWimgyPsYYNQ8q1Y

const rootJWK = await testWeave.rootJWK;