metashrew-as

Overview

The indexer standard library. Sources in this repository can be imported into indexer programs built with metashrew, and may have some utilty in other contexts.

Install

This library will be included by default in projects scaffolded with metashrew-cli, guides for which are available here:

https://github.com/sandshrewmetaprotocols/metashrew-cli)

For projects not scaffolded with metashrew-cli, it is trivial to install this library with yarn as one would for a typical JavaScript-based dependency.

yarn add https://github.com/sandshrewmetaprotocols/metashrew-as

Usage

Core indexer utilities

The following functions should be used as-is within a metashrew indexer to ensure correct functionality of the indexing process within metashrew, given the constraints of the runtime that the WASM will execute within.

get(key: ArrayBuffer): ArrayBuffer

Gets a value from the index by its key. Multiple calls to the same key are cached, and calling the set function will update the cache as well, so it is acceptable to write programs that set then later get the value at the same key within the program run for the block.

import { get } from "metashrew-as/assembly/indexer"

const KEY = String.UTF8.encode("/mykey");

export function lookup(): ArrayBuffer {
  return get(KEY);
}

set(key: ArrayBuffer, value: ArrayBuffer): void

Caches a value to be flushed to the write batch at the end of the program run. Even though no state changes are saved until the end of the program run, a call to get at any key will query the cache to lookup the value before it makes a call to the k/v store in the host environment.

import { set, get, _flush } from "metashrew-as/assembly/indexer";

const KEY = String.UTF8.encode("/mykey");

export function setvalue(): void {
  set(KEY, String.UTF8.encode("hello");
}

export function lookup(): ArrayBuffer {
  return get(KEY);
}

export function _start(): void {
  setvalue();
  _flush();
}

// can call the metashrew-view JSONRPC with the "lookup" symbol to retrive the value, 

input(): ArrayBuffer

Reads the bytevector from the host environment containing a u32 value for the block height, followed by the bytes of the serialized block.

_flush(): void

It is required to call this function, only once, at the end of your _start function. Otherwise, no state changes will be saved to the index. Always put as the last line of your _start function.

import { get, set, _flush, input } from "metashrew-as/assembly/indexer";
import { Box } from "metashrew-as/assembly/utils/box";
import { parsePrimitive } from "metashrew-as/assembly/utils/utils";

export function _start(): void {
  const data = input();
  const box = Box.from(data);
  const height = parsePrimitive<u32>(box);
  set(Box.concat([ Box.from(String.UTF8.encode("/block/")), Box.from(String.UTF8.encode(height.toString(10))); ]), box.toArrayBuffer());
  _flush();
  // trivial index sets UTF8 /block/n to the serialized block bytes, where n is 0..tip as
}

Index.keyFor(k: ArrayBuffer, k: ArrayBuffer)

Syntatic sugar over the concatenation of two ArrayBuffer byte vectors. Intended to be used as follows.

import { Index } from "metashrew-as/assembly/indexer";

export const SAMPLE_LIST = String.UTF8.encode("/mylist/");

export function getListLengthKey(): ArrayBuffer {
  return Index.keyFor(SAMPLE_LIST, String.UTF8.encode("length")); // UTF8 byte vector of /mylist/length
}

console.log

import { console } from "metashrew-as/assembly/utils/logging";

export function _start(): void {
  console.log("visible from tests or metashrew itself");
  console.logUTF8(String.UTF8.encode("sometimes we have UTF8 too and we can avoid decoding it needlessly"));
}