arlocal-sweets

Arlocal Sweets

arlocal-sweets is a small utility package that helps creating tests for SmartWeave contracts with ArLocal. The library enables developers to easily copy transactions and contracts from any Arweave gateway to an ArLocal testing gateway.

• Arlocal Sweets
  • Installation
  • Initialization
  • Usage
    • Check for test network
    • Fund Wallet
    • Mine Block
    • Copy Transaction
    • Clone Transaction (Experimental)
    • Copy Contract
    • Copy Manifest Transaction

Installation

# using npm
npm install arlocal-sweets

# using yarn legacy
yarn add arlocal-sweets

Initialization

To initialize the package, you need to have a blockweave or arweave-js instance connected with arlocal and a wallet.

Using Blockweave

  import Sweets from 'arlocal-sweets';
  import Blockweave from 'blockweave';

  const blockweave = new Blockweave({
    host: 'localhost',
    port: 1984,
    protocol: 'http'
  });

  const wallet = await blockweave.wallets.generate();

  const sweets = new Sweets(blockweave, wallet);

Using Arweave

  import Sweets from 'arlocal-sweets';
  import Arweave from 'arweave';

  const arweave = new Arweave({
    host: 'localhost',
    port: 1984,
    protocol: 'http'
  });

  const wallet = await arweave.wallets.generate();

  const sweets = new Sweets(arweave, wallet);

Usage

Check for test network

Here you can check if a network is an arlocal test network, so you don't interact with the mainnet. Interaction with the mainnet would result in an error.

await sweets.isTestNetwork(); // returns true or false

Check the unit tests to see the two present valid test networks.

Fund Wallet

To communicate with the gateway, you need to have some AR in your testnet wallet. You can easily fund your wallet with test tokens using this method.

await sweets.fundWallet(1e12); // This would fund my wallet with 1 AR

NB: The argument to the function is an integer value in winstons.
Read about winston and AR here.

Mine Block

After every transaction, your transaction has to be mined. You can mine one or many block with this method.

await sweets.mine(2); // This would mine 2 blocks

await sweets.mine(); // This would mine 1 block

Copy Transaction

Here you can copy transaction from the mainnet to arlocal testnet.

await sweets.copyTransaction('CKRSJ1s8MKk5dPl5V-bEI3FTGxK9CieI-d3c7HHbvLI'); // returns the testnet transaction ID

NB: sweets.copyTransaction takes your mainnet transaction ID as an argument.

Clone Transaction (Experimental)

This is a method which allows you copy transaction from the mainnet and retains the mainnet transaction ID, but this is an experimental feature and may cause issues. It is more advisable to use sweets.copyTransaction in place of this.

await sweets.cloneTransaction('CKRSJ1s8MKk5dPl5V-bEI3FTGxK9CieI-d3c7HHbvLI'); // returns the same mainnet transaction ID

Copy Contract

Here you can copy SmartWeave contracts from the mainnet to arlocal testnet.

await sweets.copyContract('usjm4PCxUd5mtaon7zc97-dt-3qf67yPyqgzLnLqk5A'); // returns the testnet SmartWeave contract initial state ID

NB: sweets.copyContract takes your mainnet SmartWeave contract initial state ID as an argument. This method would throw an error if the transaction ID passed is not a SmartWeave Contract state ID.

Copy Manifest Transaction

Here you can copy a full upload transaction (using the manifest ID) to arlocal testnet. It does this by re uploading all files in the manifest path and generates a new manifest.
This works only with folder uploads.

await sweets.copyManifestTransaction('FqcTfQHqgXhUG1CWoarkE2hN-rHRpbiCXxT_OGOSlJ8'); // returns the new manifest ID.

NB: sweets.copyManifestTransaction takes the manifest ID of the arkb upload. If the ID supplied is not a manifest ID an error would be thrown.