How to implement a custom writer?

10min
Summary
If you want more control over the writing part of the mintBlue Machine, you can implement a custom MintblueWriter. In this tutorial, you'll learn which methods you need to implement to build a successful custom Writer.
Prerequisites
We recommend you complete the Getting Started﻿ section before implementing a custom Writer. 
Step 1: Implementing required methods
A Writer class expects only three methods to be implemented. The fetchWriteStatus() function is optional. 
TypeScript
interface Writer {
  /** Writes action to the storage. */
  write(action: ActionWithoutId): Promise<void>;

  /** Handles errors or rejections that occur during the write process. */
  handleError(error: any): void;

  /**
   * (Optional) Fetches the confirmation or status of the written data.
   * Useful for ensuring data integrity or completion.
   */
  fetchWriteStatus?(dataId: string): Promise<string>;
}
interface Writer {
  /** Writes action to the storage. */
  write(action: ActionWithoutId): Promise<void>;

  /** Handles errors or rejections that occur during the write process. */
  handleError(error: any): void;

  /**
   * (Optional) Fetches the confirmation or status of the written data.
   * Useful for ensuring data integrity or completion.
   */
  fetchWriteStatus?(dataId: string): Promise<string>;
}
﻿
static async create(sdkToken, project_id)
async write(action)
handleError(error)
Below is the skeleton for your class. The constructor expects an initialized mintBlue client object and your project ID.
TypeScript
import { Mintblue, Action } from '@mintblue/sdk';

export class CustomMintblueWriter {
  private mintblue: Mintblue;
  private project_id: string;

  constructor(mintblue: Mintblue, project_id: string) {
    this.mintblue = mintblue;
    this.project_id = project_id;
  }

  /**
   * Factory method to create an instance of the CustomMintblueWriter.
   * Initializes the mintBlue SDK and returns a new writer instance.
   */
  static async create(sdkToken: string, project_id: string): Promise<CustomMintblueWriter> {
  
  }

  /**
   * Writes the given action as a transaction to the mintBlue platform.
   */
  async write(action: Action): Promise<void> {
    
  }

  /**
   * Handles and logs errors from the write operations.
   */
  handleError(error: any): void {
    console.log('MintblueWriter Error ' + error);
  }
}
import { Mintblue, Action } from '@mintblue/sdk';

export class CustomMintblueWriter {
  private mintblue: Mintblue;
  private project_id: string;

  constructor(mintblue: Mintblue, project_id: string) {
    this.mintblue = mintblue;
    this.project_id = project_id;
  }

  /**
   * Factory method to create an instance of the CustomMintblueWriter.
   * Initializes the mintBlue SDK and returns a new writer instance.
   */
  static async create(sdkToken: string, project_id: string): Promise<CustomMintblueWriter> {
  
  }

  /**
   * Writes the given action as a transaction to the mintBlue platform.
   */
  async write(action: Action): Promise<void> {
    
  }

  /**
   * Handles and logs errors from the write operations.
   */
  handleError(error: any): void {
    console.log('MintblueWriter Error ' + error);
  }
}
﻿
Implementation of the create() method is optional. However, it is recommended to define this method to facilitate the instantiation of the class. Direct instantiation via the constructor is not possible for a mintblue object due to the requirement of asynchronous logic.
Step 2: Adding the create() logic
The create() function is a static method to create an instance of your CustomMintblueWriter. Make sure to create a new instance of your class name. It uses an instantiated mintBlue client object and your project ID.
TypeScript
/**
 * Factory method to create an instance of the CustomMintblueWriter.
 * Initializes the mintBlue SDK and returns a new writer instance.
 */
static async create(sdkToken: string, project_id: string): Promise<CustomMintblueWriter> {
  const mintblue = await Mintblue.create({ token: sdkToken });
  return new CustomMintblueWriter(mintblue, project_id);
}
/**
 * Factory method to create an instance of the CustomMintblueWriter.
 * Initializes the mintBlue SDK and returns a new writer instance.
 */
static async create(sdkToken: string, project_id: string): Promise<CustomMintblueWriter> {
  const mintblue = await Mintblue.create({ token: sdkToken });
  return new CustomMintblueWriter(mintblue, project_id);
}
﻿
You can omit the 
Step 3: Adding the write() logic
The write logic sends an action to the mintBlue platform, writing it to storage. An action always contains the function name f and function arguments args. You must use the createTransaction function to send the data to the mintBlue platform. 
The createTransaction function expects an object with outputs. First of all, you need to send a data output. The value property expects the function name f and function arguments args. However, you can modify this object and add optional data like a time property. 
TypeScript
async write(action: Action): Promise<void> {
  if (!this.mintblue) {
    throw new Error('mintBlue SDK not initialized yet');
  }

  try {
    await this.mintblue.createTransaction({
      project_id: this.project_id,
      outputs: [
        {
          type: 'data',
          value: { f: action.f, args: action.args, time: Date.now() } as any,
          encrypt: true,
          sign: true,
        },
      ],
    });
  } catch (e) {
    this.handleError(e);
  }
}
async write(action: Action): Promise<void> {
  if (!this.mintblue) {
    throw new Error('mintBlue SDK not initialized yet');
  }

  try {
    await this.mintblue.createTransaction({
      project_id: this.project_id,
      outputs: [
        {
          type: 'data',
          value: { f: action.f, args: action.args, time: Date.now() } as any,
          encrypt: true,
          sign: true,
        },
      ],
    });
  } catch (e) {
    this.handleError(e);
  }
}
﻿
It's also possible to send multiple data outputs, like an additional data output, or a micropayment or file output. 
Here's an example with an additional data output.
TypeScript
async write(action: Action): Promise<void> {
  if (!this.mintblue) {
    throw new Error('mintBlue SDK not initialized yet');
  }

  try {
    await this.mintblue.createTransaction({
      project_id: this.project_id,
      outputs: [
        {
          type: 'data',
          value: { f: action.f, args: action.args } as any,
          encrypt: true,
          sign: true,
        },
        {
          type: 'data',
          value: { time: Date.now() } as any,
          encrypt: false,
          sign: false,
        },
      ],
    });
  } catch (e) {
    this.handleError(e);
  }
}
async write(action: Action): Promise<void> {
  if (!this.mintblue) {
    throw new Error('mintBlue SDK not initialized yet');
  }

  try {
    await this.mintblue.createTransaction({
      project_id: this.project_id,
      outputs: [
        {
          type: 'data',
          value: { f: action.f, args: action.args } as any,
          encrypt: true,
          sign: true,
        },
        {
          type: 'data',
          value: { time: Date.now() } as any,
          encrypt: false,
          sign: false,
        },
      ],
    });
  } catch (e) {
    this.handleError(e);
  }
}
﻿
How do you use a custom Writer?
Finally, let's use your CustomMintblueWriter. Ensure you import your Writer and initialize it like in the Getting Started﻿ tutorial. 
TypeScript
import { CustomMintblueWriter } from './customWriter.js';

const recorder = new MemoryRecorder();
const writer = await CustomMintblueWriter.create(sdkToken, project_id);  

const machine = new Machine(
  SupplyChain,
  await MintblueReader.create(sdkToken, project_id),
  writer,
  recorder
);
import { CustomMintblueWriter } from './customWriter.js';

const recorder = new MemoryRecorder();
const writer = await CustomMintblueWriter.create(sdkToken, project_id);  

const machine = new Machine(
  SupplyChain,
  await MintblueReader.create(sdkToken, project_id),
  writer,
  recorder
);
﻿
Verify the transaction
Additionally, you can verify if your custom Writer works as expected by inspecting your transactions in the mintBlue project overview. Navigate to your project's transactions tab, and you can verify the transaction and its data.
﻿
Click the "View" button to inspect the transaction details. You'll find a similar output with one or multiple data outputs like the JSON data below. 
JSON
[
  {
    "type": "data",
    "value": {
      "f": "plantTrees",
      "args": [
        "Belgium",
        1
      ]
    },
    "encrypt": true,
    "sign": true
  },
  {
    "type": "data",
    "value": {
      "time": 1698404885242
    },
    "encrypt": false,
    "sign": false
  },
  {
    "type": "payment",
    "to": "1FoXXU8xneLzkS1Hrhg8Hck7MJLvy3Uzyx",
    "satoshis": 24669
  }
]
[
  {
    "type": "data",
    "value": {
      "f": "plantTrees",
      "args": [
        "Belgium",
        1
      ]
    },
    "encrypt": true,
    "sign": true
  },
  {
    "type": "data",
    "value": {
      "time": 1698404885242
    },
    "encrypt": false,
    "sign": false
  },
  {
    "type": "payment",
    "to": "1FoXXU8xneLzkS1Hrhg8Hck7MJLvy3Uzyx",
    "satoshis": 24669
  }
]
﻿
Note: mintBlue adds a payment output as the last input to store the data on the chain. 
Below, you can find the full code implementation.
Code Check ✅
TypeScript
import { Mintblue, Action } from '@mintblue/sdk';

export class CustomMintblueWriter {
  private mintblue: Mintblue;
  private project_id: string;

  constructor(mintblue: Mintblue, project_id: string) {
    this.mintblue = mintblue;
    this.project_id = project_id;
  }

  /**
   * Factory method to create an instance of the CustomMintblueWriter.
   * Initializes the mintBlue SDK and returns a new writer instance.
   *
   * @param sdkToken - The SDK token for authentication with mintBlue.
   * @param project_id - The project identifier in mintBlue where the data will be written.
   * @returns A promise that resolves to a new CustomMintblueWriter instance.
   */
  static async create(sdkToken: string, project_id: string): Promise<CustomMintblueWriter> {
    const mintblue = await Mintblue.create({ token: sdkToken });
    return new CustomMintblueWriter(mintblue, project_id);
  }

  /**
   * Writes the given action as a transaction to the mintBlue platform.
   *
   * @param action - The action to write.
   * @throws Will throw an error if the mintBlue SDK has not been initialized.
   * @returns A promise that resolves when the write operation completes or rejects on error.
   */
  async write(action: Action): Promise<void> {
    if (!this.mintblue) {
      throw new Error('mintBlue SDK not initialized yet');
    }

    try {
      await this.mintblue.createTransaction({
        project_id: this.project_id,
        outputs: [
          {
            type: 'data',
            value: { f: action.f, args: action.args, time: Date.now() } as any,
            encrypt: true,
            sign: true,
          },
          {
            type: 'data',
            value: { time: Date.now() } as any,
            encrypt: false,
            sign: false,
          },
        ],
      });
    } catch (e) {
      this.handleError(e);
    }
  }

  /**
   * Handles and logs errors from the write operations.
   *
   * @param error - The error to handle and log.
   */
  handleError(error: any): void {
    console.log('MintblueWriter Error ' + error);
  }
}
import { Mintblue, Action } from '@mintblue/sdk';

export class CustomMintblueWriter {
  private mintblue: Mintblue;
  private project_id: string;

  constructor(mintblue: Mintblue, project_id: string) {
    this.mintblue = mintblue;
    this.project_id = project_id;
  }

  /**
   * Factory method to create an instance of the CustomMintblueWriter.
   * Initializes the mintBlue SDK and returns a new writer instance.
   *
   * @param sdkToken - The SDK token for authentication with mintBlue.
   * @param project_id - The project identifier in mintBlue where the data will be written.
   * @returns A promise that resolves to a new CustomMintblueWriter instance.
   */
  static async create(sdkToken: string, project_id: string): Promise<CustomMintblueWriter> {
    const mintblue = await Mintblue.create({ token: sdkToken });
    return new CustomMintblueWriter(mintblue, project_id);
  }

  /**
   * Writes the given action as a transaction to the mintBlue platform.
   *
   * @param action - The action to write.
   * @throws Will throw an error if the mintBlue SDK has not been initialized.
   * @returns A promise that resolves when the write operation completes or rejects on error.
   */
  async write(action: Action): Promise<void> {
    if (!this.mintblue) {
      throw new Error('mintBlue SDK not initialized yet');
    }

    try {
      await this.mintblue.createTransaction({
        project_id: this.project_id,
        outputs: [
          {
            type: 'data',
            value: { f: action.f, args: action.args, time: Date.now() } as any,
            encrypt: true,
            sign: true,
          },
          {
            type: 'data',
            value: { time: Date.now() } as any,
            encrypt: false,
            sign: false,
          },
        ],
      });
    } catch (e) {
      this.handleError(e);
    }
  }

  /**
   * Handles and logs errors from the write operations.
   *
   * @param error - The error to handle and log.
   */
  handleError(error: any): void {
    console.log('MintblueWriter Error ' + error);
  }
}
﻿
﻿
Updated 07 Nov 2023
Did this page help you?
How do you store snapshots in an Amazon S3 bucket?
SDK Quick Start Guide
Docs powered by Archbee
TABLE OF CONTENTS
Summary
Prerequisites
Step 1: Implementing required methods
Step 2: Adding the create() logic
Step 3: Adding the write() logic
How do you use a custom Writer?
Verify the transaction
Code Check ✅