Upload content on-chain

This document details how to use Blocknote in a standalone script. If you want to run Blocknote behind an API, users won't share their mnemonics but should instead sign with their wallet. You should refer to the BlocknoteManager section of this documentation to handle this situation.

Basic Usage

import  {Blocknote} from  "blocknote"
import fs from 'fs';

// Sends a PDF. 
// The file is encrypted with a password but the title is kept unencrypted.
const options = {   
    mime:  "application/pdf",
    title: "Sales report 2025"
}
const sender_mnemonic =  "gorilla shiver hood theory letter absorb arctic ...";
const blocknote       = new Blocknote(sender_mnemonic, options);
const file	          = fs.readFileSync("./sales_report_2025.pdf");

blocknote.save(file).then((response)=>{    
    console.log(response);
});

View a response example

{
  start: 1765932835344,
  simulation: false,
  fees: 17000,
  compression: {
    compression: "brotli",
    original_size: 19851,
    compressed_size: 15647
  },
  payload_transaction_id: "7VR62WIMCSA5POMS2QAY64SMKW5GBTN2WCBTNA5H4W3WFMYLFHWQ",
  end: 1765932851610,
  duration: 16266,
  payload: {
    title: "Sales report 2025",
    mime: "application/pdf",
    size: 19851,
    addid: 260321436,
    accid: 1583377570,
    compression: "brotli",
    txns: 16
  }
}

Constructor

Name	Description	Type
sender_mnemonic	The sender's mnemonic	string
options	See the options table below	object

Options

Name	Description	Type	Default
title	The content's title	string	Untitled
mime	The content's mime type	string	plain/text
compression	If not set, Blocknote will automaticaly choose the best compression for the given data. The compression algorithm's name: brotli, gzip, lz4, lz-string, pako, snappy "fast" will choose the fastest compression for the given content. "none" won't compress the data.	string
aes_key	An AES key to encrypt the content. Do not set an AES key if you are already encrypting with a password.	string
password	A password to encrypt the content. (The strength of the password is not verified) Do not set a password if you are already encrypting with an AES key.	string
encrypt_title	Encrypt the title. This option will be ignored if aes_key or password is not set.	boolean	true
revision_of	The initial payload transaction id of the file to update. Look at the "About revisions" table right below to understand how it works.	string
simulate	If true, transactions are not sent. This helps determine the number of algos needed for actual operations.	boolean	false
onProgress ⇒ (status)	Callback function to get the different progress statuses as they come in. View the complete list	function
onFinish ⇒ (result)	Callback executes once saving completes, including upload details in the message.	function
onError ⇒ (error)	Triggered if an error occurs while sending the batch of transactions. Note that Blocknote will always retry to send a transaction when failed, so they are not throwable errors. It is more like a log of failing transaction.	function

About revisions

The developer must refer to the initial payload transaction id of the file to revised. By consistently using the original payload transaction id in the revision_of option, the protocol can correctly track that linear chain and validate it.

Action	revision_of	Notes
Initial upload	null	Creates a payload transaction id: LMO4POL ...
First revision	LMO4POL ...	References the original payload id
Second revision	LMO4POL ...	Still references the original payload id
Third revision	LMO4POL ...	Always reference the original payload id

Branching Revisions (Advanced/Experimental)

Action	revision_of	Notes
Initial upload	null	Creates a payload transaction id: LMO4POL ...
First revision	LMO4POL ...	References the original payload id. Creates its own payload transaction id: VBHDO2Z ...
Second revision	LMO4POL ...	Still references the original payload id. Creates its own payload transaction id: PWX8BZOL ...
First revision of the second revision	PWX8BZOL ...	References the payload id of the second revision. A new branch starts here.

While branching is technically possible, most use cases should stick to the linear model by always referencing the original payload transaction id. Branching may complicate version tracking and resolution depending on how your application queries and displays revision history. Feel free to experiment but the BlocknoteReader doesn't support branching out-of-the-box.

---

Methods

save

Parameters

Name	Description	Type
raw_content	The content to upload	string, Uint8Array, Buffer

Return

A promise that contains the upload details and the payload.