Skip to content

Serialization library geared towards immutable data storage such as blockchains.

Notifications You must be signed in to change notification settings

EOSIO/eosjs-fcbuffer

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

88 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Build Status Coverage Status NPM

FC Buffer

Serialization library geared towards immutable data storage such as blockchains.

For EOS compatible implementation use this library from eosjs instead.

FC Buffer is a recent refactor from serialization code used in Bitshares and Steem. Some of the serialization code was reduced and the definitions language added. The definition format may change.

Features

  • Validation and error reporting
  • Concise and intuitive binary format
  • Compatible with the FC library used in Graphene blockchains
  • Extendable JSON structure definitions
  • Binary and JSON string serialization
  • Unit testing and code coverage

Non Features

  • Consider Cap'n Proto or Protocol Buffers if your data structures need to be extended at the serialization layer.
  • No streams, smaller blockchain sized objects are used

Example

Fcbuffer = require('fcbuffer') // or: Fcbuffer = require('./src')

assert = require('assert')

definitions = {
    message_type: 'fixed_string16', // CustomType: built-in type
    account_name: 'fixed_string32', // CustomType: built-in type
    message: { // struct
        fields: {
          from: 'account_name',
          to: 'account_name',
          cc: 'account_name[]',
          type: 'message_type',
          data: 'bytes' // built-in type
        }
    }
}

// Warning: Do not use {defaults: true} in production
fcbuffer = Fcbuffer(definitions, {defaults: true})

// Check for errors anywhere in the definitions structure
assert(fcbuffer.errors.length === 0, fcbuffer.errors)

// If there are no errors, you'll get your structs
var {message} = fcbuffer.structs

// Create JSON serializable object
// returns { from: '', to: '', cc: [ '' ], type: '', data: '' }
message.toObject()

// Convert JSON into a more compact fcbuffer serializable object
msg = { from: 'jc', to: 'dan', cc: [ 'abc' ], type: '', data: '0f0f0f' }

// Serialize fcbuffer object into a single binary buffer
buf = Fcbuffer.toBuffer(message, msg)
// returns <Buffer 02 6a 63 07 63 68 61 72 6c 65 73 01 03 61 62 63 00 03 0f 0f 0f>

// Convert binary back into a new (cloned) object
obj = Fcbuffer.fromBuffer(message, buf)

// Check that the new object matches the original
assert.deepEqual(msg, obj)

// A definition may extend and define other definitions.  This works in the initial
// definition or later via the extend function.
fcbuffer2 = fcbuffer.extend({
    permission_name: 'fixed_string16',
    permission_level: {
        fields: {
          actor: 'account_name',
          permission: 'permission_name'
        }
    }
})

assert(fcbuffer2.errors.length === 0, fcbuffer2.errors)

var {permission_level} = fcbuffer2.structs
permission_level.toObject()
// toObject returns: { actor: '', permission: '' }

References

Environment

Node 6+ and browser (browserify, webpack, etc)

About

Serialization library geared towards immutable data storage such as blockchains.

Resources

Stars

Watchers

Forks

Packages

No packages published

Languages

  • JavaScript 98.8%
  • HTML 1.2%