bpu

README

go-bpu

Transform Bitcoin Transactions into Virtual Procedure Call Units (Bitcoin Processing Unit)

Transforms raw transactions to BOB format. Port from the original bpu library by unwriter

Since this is intended to be used by low level transaction parsers dependencies are kept to a bare minimum. It does not include the RPC client functionality that connects to a node to get a raw tx. It's designed to be a fast raw tx to BOB processor.

There is also a Typescript version which does include the originally RPC functionality.

Installation

go-bpu requires a supported release of Go.

go get -u github.com/bitcoinschema/go-bpu

Documentation

View the generated documentation

Usage

Split Config

var separator = "|"
var l = bpu.IncludeL
var opReturn = uint8(106)
var opFalse = uint8(0)

var splitConfig = []SplitConfig{
	{
		Token: &Token{
			Op: &opReturn,
		},
		Include: &l,
	},
	{
		Token: &Token{
			Op: &opFalse,
		},
		Include: &l,
	},
	{
		Token: &Token{
			S: &separator,
		},
    Require: &opFalse,
	},
}

bpuTx, err := Parse(ParseConfig{RawTxHex: &sampleTx, SplitConfig: splitConfig, Mode: *bpu.Shallow})
if err != nil {
  fmt.Println(err)
}

Transaction Source

You can either use SplitConfig.RawTxHex and set by hex string, or use SplitConfig.Tx to set by bt.Tx.

Transform Function

You can pass an optional Transform function to bpu.Parse. Function should look something like this:

var splitTransform Transform = func(o Cell, c string) (to *Cell, e error) {
	// if the buffer is larger than 512 bytes,
	// replace the key with "l" prepended attribute
	to = &o
	bytes, err := hex.DecodeString(c)
	if err != nil {
		return nil, err
	}
	if len(bytes) > 512 {
		to.LS = to.S
		to.LB = to.B
		to.S = nil
		to.B = nil
	}
	return to, nil
}

More Usage details

See the Typescript library README for more examples of split configuration options, transformation, and a look at the output.

Errata

The original BPU library used bsv (javascript) v1.5 to determine if a script chunk was a valid opcode. At the time, the bsv library supported a limited number of OP codes (inherited from limitations imposed by Bitcoin core). In this version all opcodes are recognized which surfaces a new issue where fields previously available would be missing if the data is now recognized as an opcode.

Previously, BPU would omit the op and ops fields for non opcode data, while recognized opcodes would omit the s, b and h fields. To solve the issue of missing fields that happen to be opcodes, all keys are included if the recognized pushdata is also in the Printable ASCII range.

Contributing

View the contributing guidelines and follow the code of conduct.

How can I help?

All kinds of contributions are welcome 🙌! The most basic way to show your support is to star 🌟 the project, or to raise issues 💬. You can also support this project by becoming a sponsor on GitHub 👏 or by making a bitcoin donation to ensure this journey continues indefinitely! 🚀

License

Documentation

Overview

Package bpu contains the main functionality of the bpu package

Index

• type Blk
• type Cell
• type E
• type IncludeType
• type Input
• type Mode
• type Output
• type ParseConfig
• type SplitConfig
• type Tape
• type Token
• type Transform
• type Tx
  • func Parse(config ParseConfig) (bpuTx *Tx, err error)
• type TxInfo
• type XPut

Types

type Blk

type Blk struct {
	I uint32 `json:"i"`
	T uint32 `json:"t"`
}

Blk contains the block info

type Cell

type Cell struct {
	H   *string `json:"h,omitempty" bson:"h,omitempty"`
	B   *string `json:"b,omitempty" bson:"b,omitempty"`
	LB  *string `json:"lb,omitempty" bson:"lb,omitempty"`
	S   *string `json:"s,omitempty" bson:"s,omitempty"`
	LS  *string `json:"ls,omitempty" bson:"ls,omitempty"`
	I   uint8   `json:"i" bson:"i"`
	II  uint8   `json:"ii" bson:"ii"`
	Op  *uint8  `json:"op,omitempty" bson:"op,omitempty"`
	Ops *string `json:"ops,omitempty" bson:"ops,omitempty"`
}

Cell is a single OP_RETURN protocol

type E

type E struct {
	A *string `json:"a,omitempty" bson:"a,omitempty"`
	V *uint64 `json:"v,omitempty" bson:"v,omitempty"`
	I uint32  `json:"i" bson:"i"`
	H *string `json:"h,omitempty" bson:"h,omitempty"`
}

E has address and value information

type IncludeType

type IncludeType string

IncludeType is the type of include

const (
	IncludeL IncludeType = "l"
	IncludeR IncludeType = "r"
	IncludeC IncludeType = "c"
)

Include types

type Input

type Input struct {
	XPut
	Seq uint32 `json:"seq" bson:"seq"`
}

Input is a transaction input

type Mode

type Mode string

Mode is either deep or shallow

const (
	// Deep mode evalurates every pushdata regardless of quantity
	Deep Mode = "deep"
	// Shallow mode only evaluates the first 128 pushdata and the last 128 pushdatas
	Shallow Mode = "shallow"
)

type Output

type Output struct {
	XPut
}

Output is a transaction output

type ParseConfig

type ParseConfig struct {
	Tx          *bt.Tx        `json:"tx" bson:"tx"`
	RawTxHex    *string       `json:"rawTx" bson:"rawTx"`
	SplitConfig []SplitConfig `json:"split,omitempty" bson:"split,omitempty"`
	Transform   *Transform    `json:"transform,omitempty" bson:"transform,omitempty"`
	Mode        *Mode         `json:"mode,omitempty" bson:"mode,omitempty"`
}

ParseConfig is the configuration for parsing a transaction

type SplitConfig

type SplitConfig struct {
	Token   *Token       `json:"token,omitempty" bson:"token,omitempty"`
	Include *IncludeType `json:"include,omitempty" bson:"include,omitempty"`
	Require *uint8       `json:"require,omitempty" bson:"require,omitempty"`
}

SplitConfig is the configuration for splitting a transaction

type Tape

type Tape struct {
	Cell []Cell `json:"cell"`
	I    uint8  `json:"i"`
}

Tape is a tape

type Token

type Token struct {
	S   *string `json:"s" bson:"s"`
	B   *string `json:"b" bson:"b"`
	Op  *uint8  `json:"op" bson:"op"`
	Ops *string `json:"ops" bson:"ops"`
}

Token is a token to split on

type Transform

type Transform func(o Cell, c string) (to *Cell, err error)

Transform is a function to transform a cell

type Tx

type Tx struct {
	In   []Input  `json:"in"`
	Out  []Output `json:"out"`
	ID   string   `json:"_id"`
	Tx   TxInfo   `json:"tx"`
	Blk  Blk      `json:"blk"`
	Lock uint32   `json:"lock"`
}

Tx is a BOB formatted Bitcoin transaction

func Parse

func Parse(config ParseConfig) (bpuTx *Tx, err error)

Parse is the main transformation function for the bpu package

type TxInfo

type TxInfo struct {
	H string `json:"h"`
}

TxInfo contains the transaction info

type XPut

type XPut struct {
	I    uint8  `json:"i"`
	Tape []Tape `json:"tape"`
	E    E      `json:"e,omitempty"`
}

XPut is a transaction input or output