Transmute Framework

0.2.5 verified Sat Apr 25 auth: no javascript

Transmute Framework is a JavaScript library for building decentralized applications on Ethereum and IPFS. It converts JavaScript objects to IPFS hashes and stores them on Ethereum smart contracts, enabling immutable event logs and event-sourced models. The latest stable version is 0.9.3, released after a major refactor adding JOSE/COSE/SCITT support. The project appears to be in active development but with infrequent releases (major versions months apart). Key differentiators include Redux-like event stream processing, built-in EventStore contracts, and support for multiple environments (local Ganache, Minikube, cloud). Alternative frameworks like Truffle and Embark offer broader dApp development features but less focus on event sourcing and IPFS integration.

Common errors

error Error: Cannot find module 'transmute-framework' ↓

cause Package not installed or import path incorrect.

fix

Run npm install transmute-framework and ensure import path is correct.

error Error: EventStore is not a constructor ↓

cause Using wrong import style (e.g., require instead of import).

fix

Use import { EventStore } from 'transmute-framework'; for ESM.

error Error: write is not a function ↓

cause EventStore not initialized properly (init() not called).

fix

Await eventStore.init() before calling write().

error Error: connect ECONNREFUSED 127.0.0.1:5001 ↓

cause IPFS daemon not running or wrong port.

fix

Start ipfs daemon and check ipfsConfig host/port.

error Error: Returned error: VM Exception while processing transaction: revert ↓

cause Contract call reverted (e.g., invalid event format or not owner).

fix

Check EventStore contract address and event structure; ensure account is owner.

Warnings

breaking BREAKING CHANGE: Major refactor in v0.9.0 - renamed several exports and changed IPFS/Ethereum configuration schema. ↓

fix Update imports and config to new schema documented in migration guide.

breaking BREAKING CHANGE: v0.9.0 switched to ESM-only exports. CommonJS require() will not work in Node.js without ESM flags. ↓

fix Use import syntax or run Node with --experimental-modules flag.

deprecated DEPRECATED: EventStoreFactory.createEventStore() no longer accepts a callback; use async/await. ↓

fix Replace callback pattern with await createEventStore(account).

gotcha Encryption is not handled by the framework. Sensitive data stored on Ethereum/IPFS is public. ↓

fix Encrypt data before passing to EventStore.write(). Use libraries like crypto-js.

gotcha EventStore contract must be deployed first via migration or EventStoreFactory; writes will fail if contract not found. ↓

fix Run truffle migrate before using EventStore. Check contract address.

gotcha IPFS and Ethereum nodes must be running and accessible; errors with 'connect ECONNREFUSED' indicate misconfiguration. ↓

fix Verify IPFS daemon and Ganache are running, and ports match transmuteConfig.

Install

npm install transmute-framework

yarn add transmute-framework

pnpm add transmute-framework

Imports

EventStore

wrong

const EventStore = require('transmute-framework');

correct

import { EventStore } from 'transmute-framework';

Package is ESM-only as of v0.9.x. CommonJS require may not work.

EventStoreFactory

wrong

const EventStoreFactory = require('transmute-framework').EventStoreFactory;

correct

import { EventStoreFactory } from 'transmute-framework';

Named export, not default. Also available via CJS destructuring but ESM recommended.

TransmuteConfig

wrong

import TransmuteConfig from 'transmute-framework';

correct

import { TransmuteConfig } from 'transmute-framework';

TypeScript type/interface export, not a default export. Use type import if needed.

Quickstart

Initializes EventStore with local Ganache and IPFS, writes a key-value event, and reads event slice.

// Install dependencies
// npm i transmute-framework web3 ipfs-http-client

import { EventStore, EventStoreFactory } from 'transmute-framework';
import Web3 from 'web3';
import ipfsHttpClient from 'ipfs-http-client';

// Configuration for local Ganache and IPFS
const transmuteConfig = {
  ipfsConfig: {
    host: '127.0.0.1',
    port: 5001,
    protocol: 'http'
  },
  web3Config: {
    providerUrl: 'http://127.0.0.1:8545'
  }
};

// Initialize EventStore contract
const eventStore = new EventStore({
  eventStoreArtifact: require('./build/contracts/EventStore.json'),
  ...transmuteConfig
});

async function main() {
  await eventStore.init();
  const accounts = await eventStore.web3.eth.getAccounts();

  // Write an event
  const event = {
    key: {
      type: 'ACCOUNT_CREATED',
      value: accounts[0]
    },
    value: {
      name: 'Alice'
    }
  };
  await eventStore.write(accounts[0], event.key, event.value);

  // Read events
  const events = await eventStore.getSlice(0, 10);
  console.log('Events:', events);
}

main().catch(console.error);