Peer-to-Peer Transactions

BSV enables direct transactions between parties without the need for a trusted third party, reducing transaction costs and increasing efficiency​​​​.

Lower Transaction Fees

BSV's efficient design supports micropayments and low-value transactions with minimal fees, making it ideal for small casual transactions and enabling new business models.

Efficiency in Payment Systems

BSV transactions are confirmed within seconds, making it suitable for time-sensitive transactions without the delays common in traditional banking systems​​.

Flexibility in Use Cases

BSV supports a variety of applications beyond simple payments, including smart contracts, tokens, and complex data operations - all on one blockchain layer - enhancing its utility while maintaining its native efficiency.

Tokenization

BSV Blockchain is a massively scalable utxo based system. What this means is that each transaction output can be dealt with independently by different systems, without worrying about any global state. This means transaction throughput is theoretically unbounded.

There have been many token protocols defined on top of BSV over the years. The most basic way to create a token system on BSV is to simply use an Overlay Service to track specific utxos which have been "minted" as tokens via some tokenization method.

Single Use

If we don't care to track tokens beyond their first spend we could build some simple logic into an overlay which defines a the token as "any utxo which has this specific txid". That way any transaction will be accepted by the overlay so long as it is spending one of a specific set of outputs from a single transaction. You could imagine the use case is a redeemable voucher for $5 off from a local store as part of some promotion.

Say it yields the txid 76730e3d92afcf6a28f8a43bb2c6783685b18170a8da31168364c7b73c9893f3 then we can set the overlay to accept transactions only if one or more inputs contain that txid.

This limits us to either knowing the desired owners of each token at the time on minting, setting the public key hash accordingly; or using a server side private key which pre-signs the utxos with sighash none & anyone can pay before delivering them to a particular owner. This allows them to pass this information around as they see fit, eventually constructing a transaction which spends the utxo using that existing signature, simply adding an arbitrary output when needed.

You can see from this simple example that the meaning of the token is defined by the issuer, and is only redeemable with them.

Multi Use

Creating tokens which can be transferred multiple times while retaining their meaning involves tracing their outputs from one to another.

This can be handled again by a simple overlay which accepts minting transactions as well as transfer transactions and burn transactions.

How you consider the tokens to exist and transfer can be in a push data denomination, or an ordinals approach.

Push Data approach

The idea here is that you mint tokens by pushing a blob of data to denominate the value the token represents while not really caring how many satoshis are associated. In other words 1 satoshi is sufficient for any denomination.

For example a JSON push data might look like:

This would be pushed to the script as a blob of data which is then dropped off the stack prior to executing a regular locking script function.

Thereafter, these tokens are spendable only within the context of the token's issuing overlay. In other words, each spend needs to be send to that overlay such that the new token outputs can be noted for eventual redemption / burning at the end of the token lifecycle.

Transfer transactions would like something like:

The simple rule being "to accept an inbound transaction it must have equal inputs and outputs of each token type.

From the minting transaction onward the issuer of the tokens keeps a working UTXO set of all their tokens, updating them as new transactions come in. This allows them to enforce rules as they deem appropriate for their particular use case.

Ordinal Approach

This would involve using the satoshis themselves to represent specific denominations and using the order of satoshis in the inputs and outputs to define where the tokens were being transfered, rather than the push data.

A transfer would then look like:

In this case, the 0th output would now contain 5 sometokens, and the 1st output would contain 5 sometokens and 9 memecoins. The push data in the inputs refers to token type and token to satoshi ratio.

Thereafter there would be no need for push data, just satoshi values, the tokens would transfer using the order of satoshis in subsequent transactions, thus offering a higher degree of privacy.

Offline Transactions

Fundamentally the benefit of tokens over account based payment systems is that each transfer is independent of all other transfers. This means you can do offline payments, chain a bunch of payments together, and then broadcast everything when you next connect to arrive at a valid confirmed state. Many people can all do this simultaneously, so there is no upper bound to the number of transactions per second which can be facilitated in this way. Payments can occur entirely P2P and settlement can be asynchronous without any underlying issue.

Bad actors cannot fake their tokens since they come with Merkle paths, so fraud is significantly more difficult. Given the time to settle is 80ms or so once connected, there's no incentive to attempt it - you don't know whether the receiving party is connected or not.

Data Integrity

BSV Blockchain provides a globally distributed timestamp server backed by proof of work. What this means is that every block added to the chain is linked to a previous block such that all history of transactions remains immutable. The security of this model is that the chain of hashes is broadly distributed, ideally to all users of the system. This constitutes a very small amount of data - 80 bytes every 10 minutes - while incorporating proof of inclusion for an unbounded number of transactions.

Implementation

Broadly speaking the idea is to contain a proof that some data existed in a transaction which is submitted for inclusion within the blockchain. When a valid block is found, the transaction is in effect timestamped as having existed at that point in time at that specific block height. We can then use the transaction itself, a Merkle path, and the block header to prove it mathematically. This allows us to provide proof that the data within the transaction has not changed at all since its inclusion.

The key primitive which allows this is something called a Cryptographic Hash Function, specifically in BSV we use sha256. If we want to prove data integrity privately, we can publish a hash of the data rather than the data itself.

What this requires is a server to host the data, and a client which knows how to run the proof. The data can be stored like so:

The exact format in terms of the hash algo used, where the push data is within the output, whether it's signed, can all be decided by the implementer based on their needs.

What you can then do as a consumer of the data to check integrity is make a request to the server holding this information. You retrieve the data, which you then hash and check against the transaction data to verify inclusion. Then you run transaction verification:

WhatsOnChain provides headers in the example code above - but in an ideal world you would be checking against your own Block Headers Service. We provide free open source software which will get and maintain an independently validated chain of headers you can reference to validate data independently. This is the one thing which is actually important to distribute broadly.

Operating an SV Node within the BSV Blockchain requires a proactive approach to security, particularly in safeguarding against Distributed Denial of Service (DDoS) attacks. These attacks aim to disrupt service by overwhelming the node with traffic, posing a significant risk to network stability and data integrity. Effective port management is a cornerstone of node security, emphasizing the importance of limiting open ports to those essential for operations. Special consideration should be given to port 8333, the default for peer-to-peer (P2P) communications, which, while not a frequent target, is vulnerable to DDoS attacks due to its critical role in network connectivity.

This guide offers targeted strategies and configurations to fortify SV Nodes against DDoS threats, focusing on optimizing maxconnections and maxconnectionsfromaddr settings, alongside deploying UFW rules to rate limit incoming traffic on port 8333. Implementing these measures enhances the resilience of the node, ensuring the BSV Blockchain network remains robust and reliable against external disruptions.

The BSV Skills Center is a comprehensive collection of documents covering all aspects of BSV Blockchain system. Technology, philosophy, legal, and economic topics are included, along with practical guides for those who want to build on top of it.

Where should I begin?

The Bitcoin white paper defines the actions of a node in section 5:

1. New transactions are broadcast to all nodes.

2. Each node collects new transactions into a block.

3. Each node works on finding a difficult proof-of-work for its block.

Introduction

The Network Access Rules is the set of rules regulating the relationship between the BSV Association and the nodes on BSV. It details their duties and obligations to the network and their relationship with the Association. The rules are grounded in the principles of the Bitcoin Protocol and the Bitcoin White Paper, ensuring that all nodes contribute to a lawful and honest network environment, providing transparency and guidance for network participants. Network activities in this instance include collecting, validating, or accepting a block, collating transactions into a block, attempting to find a proof-of-work for a block, or broadcasting a block.

Version: 1

Upload Date: 15/02/2024 Changelog:

• 27/02/2024: Minor v1 grammatical and formatting corrections and added FAQ

The Bitcoin SV Bug Bounty Program only applies to the code for the Bitcoin SV full node implementation.

We certainly appreciate any issues with the website reported to us. But as we use largely off the shelf products for the website and the website is informational in nature, the Bug Bounty Program does not apply to the website.

Immunefi Bitcoin SV Bounty Program

There are 4 defined “networks”:

• mainnet – the main public network.

• STN (S_caling Test Network_) – a public test network targeted at testing scaling.

• testnet – a public test network, typically used for testing of software before release.

• regnet – a private “regression” test network, meant for local testing.

Nodes from different networks can co-exist on the same physical network; each public network uses a different set of seed nodes (if any) and ports for communications.

The BSV server software defaults to mainnet.

The getminingcandidate RPC call is an improved API for Miners, ensuring they can scale with the Bitcoin network, by mining large blocks without the limitations of the RPC interface interfering as block sizes grow. Based on and credited to the work of Andrew Stone and Johan van der Hoeven, GMC works by removing the list of transactions from the RPC request found in getBlockTemplate and supplying only the Merkle proof of all the transactions currently in the mempool/blockcandidate.

It is strongly recommended that Miners begin the necessary steps to adapt their mining pool software to use GMC. As block sizes grow, Miners still using getBlockTemplate will begin to run into issues trying to produce blocks. At best, they will be leaving fees on the table for other Miners, and at worst their mining environment will fall behind the chain tip as they are waiting on block templates to be generated, in some cases bringing block production to a complete stand still.

For Miners wishing to test the limitations of their pool setup it is recommended they start a test deployment on the Scaling Testnet.

Database

A Postgres DB used to store user accounts, transactions, utxos, public keys, accounts, and metadata.

Cache

The cache is used for handling spikes in usage of the application. The idea being all requests can be queued and responses made on a FIFO basis.

This is a UI for the SPV Wallet server that allows you to inspect stored data and metadata. It enables the manual addition of user accounts and facilitates paymail transactions. This tool is especially helpful for troubleshooting purposes.

This component does the heavy lifting. It exposes the secure Client API, and public Paymail Endpoints; runs SPV on inbound transactions; stores transactions and metadata; and broadcasts valid transactions, exposing a callback for Merkle paths.

At a high level there are admin functionalities exposed like creating a new alias, adding a new xpub, deleting things.

The client functionality is more about drafting new transactions, modifying them, signing an actioning them in terms of sending to counterparty hosts, generating new locking scripts.

The public facing endpoints are all associated with Paymail service discovery and capabilities, which are detailed in Payments Flow.

It is recommended to configure the webhook functionality to ensure that node operators are aware when alerts are published. The webhook is only fired if the ALERT_SYSTEM_ALERT_WEBHOOK_URL is set. When set, all alerts received will issue a POST request to this endpoint with the following payload:\

{
    "alert_type": <uint32>,
    "raw": <raw hex string of the alert>,
    "sequence": <uint32>,
    "text": <human readable alert message string>
}

This format natively supports Slack webhooks, but any customizable operational procedure can be handled with this webhook.

PART IV - DISPUTE RESOLUTION RULES

1. Arbitration

   1. Any dispute, controversy, or claim arising out of, or in relation to, the Rules, including regarding the existence, validity, invalidity, breach, or termination thereof, will be resolved by arbitration in accordance with the Swiss Rules of International Arbitration of the Swiss Arbitration Centre in force on the date on which the Notice of Arbitration is submitted in accordance with those rules (the ‘Swiss Rules’). In particular:

      1. (a) the number of arbitrators will be one or three;

      2. (b) when designating or appointing an arbitrator, the parties, the arbitrators, and the Arbitration Court of the Swiss Arbitration Centre, in view of securing the appointment of a qualified, independent and impartial arbitrator, are invited to consider the opportunity, as appropriate, of designating or appointing arbitrators of the P.R.I.M.E. Finance Panel of Experts and any of the specialised panels that P.R.I.M.E. Finance may form to deal with particular categories of blockchain or digital assets-related cases;

      3. (c) the seat of the arbitration will be Zug, Switzerland;

   2. Binding nature

      1. The arbitration agreement in clause IV.1 is binding on each Node, irrespective of when that Node first undertakes or undertook a Relevant Activity.

   3. Changes

      1. This Part IV (Dispute Resolution Rules) (including the arbitration agreement in clause IV.1) is subject to change in accordance with clause II.5 of the Rules.

      2. Any changes to this Part IV (Dispute Resolution Rules) will not result in the arbitration agreement in clause IV.1 ceasing to have binding effect.

A smart contract is a self-executing contract where terms of the contract are implemented in code. A common misconception is that Bitcoin is incapable of executing smart contracts, paving the way for the creation of other blockchains like Ethereum.

The bitcoin scripting language is designed to be as primitive as possible. Using a set of OP codes, the language achieves maximum security while minimising attack surfaces through intentional limitations, which often leads to an underestimation of Bitcoin’s true potential. In fact, by simply focusing on the Bitcoin scripting language, there is a risk that many other interesting features of the protocol may be overlooked. To understand how Bitcoin is smart-contract friendly, one needs to zoom in and out on the bitcoin transaction, as well as the entire stage on which the bitcoin transaction plays its role.

By doing this, it becomes apparent that there are many ways to construct smart contracts on bitcoin. We can summarise them roughly as

• smart locking scripts

• smart use of sighash flags

• layered networks

• payment channels.

\

The SPV Wallet broadcasts all valid transactions it receives or creates to ARC.

ARC Endpoints

We use the first endpoint to determine the correct fee model to use when creating a transaction.

Thereafter we simply broadcast to ARC and expect a SEEN_ON_NETWORK txStatus response in most cases.

Usually a callbackUrl would be set for async status updates - but if you'd like to manually check the most recent state of a given transaction, you can use this:

Bitcoin uses a scripting system for transactions, specifically output locking scripts. Similar to Forth, Script is simple, stack-based, language that is processed from left to right as a series of sequential instructions. Data is pushed onto the stack and opcodes are used to perform operations on the items on the stack.

Script is Turing-complete despite not having jump instructions. Finite state machines can be built which hold their current state in one or more UTXOs. Among other methods, these machines can receive information from oracles, generate deterministic pseudo random values or look back to previous transactions on the ledger for the data needed to determine the next-state. A loop is formed by checking these input conditions and asserting a particular output state for the next UTXO holding the Turing machine. In this way, the Turing machine is held in a continually operating state until such a time as a transaction is created that determines that the process can halt. One such technique called 'OP_PUSH_TX' uses the ECDSA message pre-image to enforce conditions for the next stages of each computation. Techniques that are considered Turing complete can be described as using the Bitcoin ledger as an unbounded ticker tape to store computational results and future instructions.

A transaction output script is a predicate formed by a list of instructions that describe how the next person wanting to transfer the tokens locked in the script must unlock them. The script for a typical P2PKH script requires the spending party to provide two things:

a public key that, when hashed, yields the destination address embedded in the script, and a signature to prove ownership of the private key corresponding to the public key just provided. Scripting provides the flexibility to change the parameters of what's needed to spend transferred bitcoins. For example, the scripting system could be used to require two private keys, or a combination of several keys, or even a file and no keys at all. The tokens are unlocked if the solution provided by the spending party leaves a non-zero value on the top of the stack when the script terminates.

Simplified Payment Verification (SPV) is a method in Bitcoin that allows receivers in a peer-to-peer or P2P transaction to rapidly mitigate the possibility that the transaction's inputs have already been spent without running a node.

This technique leverages the properties of the blockchain to ensure that a transaction has been included in the blockchain without the need to download and verify the entire blockchain history.

Concept of SPV

• Definition: SPV enables users to confirm that a transaction has been included in a block and thus is part of the blockchain without needing to validate the entire blockchain. This is accomplished by using the longest chain of block headers and the specific Merkle branch related to the transaction being verified to perform a Merkle proof and match the result against the Merkle root of the relevant block header.

Deployment of Bitcoind can be done in many ways, depending on the requirements of your deployment, it could be fairly minimal, or very involved.

Before undertaking such a process, it is important to consider if you really need a Bitcoin node. Services such as ARC provide transaction processing and informational services to merchants, exchanges and anyone else who needs to interact with the blockchain without the encumbrance of running a Bitcoin node themselves.

If you are a Miner, at the bare minimum you will need to by running bitcoind and setup the .

Recommendation for non-mining entities

The BSV Association has been advocating for non-mining entities (exchanges and other applications) to remove their reliance on the SV Node software for daily operations because of the constantly increasing traffic on the BSV network.

The Mandala Upgrade is a significant advancement in the blockchain network, enhancing scalability, cost-efficiency, and overall performance. This upgrade primarily focuses on improving the Bitcoin SV (BSV) network, making it more robust and suitable for enterprise solutions.

Key Components

Teranode

SV Node is a full node implementation for the BSV Blockchain, developed by the BSV Association. It allows users to run a full node on the BSV network to validate transactions and blocks.

The SV Node software is written in C++ and focuses on performance, scalability, and enterprise-grade operations. Key features include support for massive block sizes, parallelized validation for high throughput, fee management controls, security hardening, detailed logging, and monitoring integrations. SV Node aims to provide a robust and reliable full node solution for professional use cases like mining operations, enterprise applications, and service providers building on the BSV Blockchain.

This documentation provides an overview of the SV Node software, but it is not intended as a definitive source for dictating settings that miners should or should not use. Instead, it serves as a guide to help you understand the , , and steps for . Before proceeding with the installation, it is recommended to carefully review the sections on architecture and system requirements, as they contain essential information for running SV Node effectively.

What is a Hash?

In the context of computer science, a hash is a function that converts an input (or 'message') into a fixed-size string of bytes. The output, typically a 'digest', represents concisely the original input data. A hash function is a type of one-way function, meaning it's easy to compute a hash from a given input but nearly impossible to recreate the original input just by knowing the hash value. This property ensures data integrity, as any alteration of the input data will result in a dramatically different hash.

For convenience, there is a helper script with the SV Node software release that will automate the startup of the Alert System in conjunction with the SV Node daemon. This script will startup the Alert System and wait for it to be synced and healthy prior to starting the bitcoind daemon. To view the help for the script, run:

This script assumes that the alert-system, bitcoind, bitcoin-cli binaries are in the system's PATH.

Example when using the installation guide:

It also expects that the user has configured the needed environment variables as outlined above for the user-specific configuration.

Example call

Background to the Rules

• A. BSV Association (the ‘Association’ or ‘we’, ‘our’, or ‘us’) is a non-profit organisation based in Switzerland. Our goals are to support the operation of the Network and foster the growth of the Bitcoin Satoshi Vision (‘Bitcoin’, ‘Bitcoin SV’, or ‘BSV’) ecosystem. We aim to achieve this by protecting and supporting the vision of ‘Satoshi Nakamoto’ in the paper ‘Bitcoin: A Peer-to-Peer Electronic Cash System

Teranode is the next-generation node software for the BSV Blockchain, designed to achieve massive scalability through a distributed microservices architecture. Unlike traditional monolithic node implementations, Teranode breaks down blockchain processing into specialized components that can scale horizontally across multiple servers.

The Teranode architecture enables the BSV network to process millions of transactions per second by parallelizing and distributing core blockchain functions including transaction validation, block assembly, mempool management, and state persistence. Key features include distributed processing across microservices, horizontal scalability to handle enterprise-level throughput, optimized resource utilization through specialized components, and support for the BSV network's unbounded scaling roadmap.

Teranode represents a fundamental reimagining of blockchain node infrastructure, moving from single-server limitations to a cloud-native distributed system capable of supporting global-scale applications. This architecture allows the BSV Blockchain to handle transaction volumes comparable to major payment networks while maintaining the security and decentralization properties of a public blockchain.

External (p2p network):

• discovers and connects to other nodes

• send and receive messages to and from other nodes

Internal:

• exposes RPC to pool software and other tools

The SPV Wallet uses Paymail capabilities to publicly reveal their ability to interpret SPV transaction data.

Deploying the SPV Wallet will spin up a number of containerized services to create something which at a high level looks like the diagram below.

We see that there are two user interfaces, the Wallet App, and the Admin Console. These drive an API hosted by the SPV Wallet Server. This Wallet Server also accepts payments from Other Wallets, and Broadcasts Transactions to ARC. ARC returns Merkle Paths to confirm transactions, which are validated by checking Merkle roots stored by Blockheader Service.

The SPV Wallet combines the components to form a fully operational hosted non-custodial open-source reference wallet for the ecosystem.

Table of Contents

The following does not constitute legal advice. All relevant issues cannot be considered. The assumption is that, where appropriate, miners will consult with their legal advisers and any other adviser they deem appropriate.

Disclaimer

The content of this document is provided for informational purposes only and is not intended to modify or supersede the contractual rights or obligations of any party to the Network Access Rules. Parties are encouraged to carefully review the Network Access Rules to verify the accuracy of the information presented here. It is assumed that, where necessary, parties will seek guidance from their legal counsel and any other advisors they consider necessary.

Any statements here do not purport and should not be considered to be a guide to, advice on, or explanation of all relevant issues or considerations relating to the contractual relationship established by the NAR. The BSV Association assumes no responsibility for any use to which the BSV network is put by any miner or other third party.

If a node believes it has detected a potential Withholding attack, the node will enter safe mode and the wallet functionality (e.g. getbalance) will be disabled as a protective measure. At this point a miner should stay alert and be prepared to take manual intervention.

Withholding attacks can be neutralised by calling the invalidateblock RPC on the block at the base of the attack chain. The local node will then consider the entire attack chain as no longer valid.

Safe mode will be triggered by the presence of a chain fork longer than that specified by the configuration parameter safemodeminforklength (defaults to 6). It is possible that in exceptional circumstances such a fork can be produced normally. i.e. by a node that is not under attack.

Once a node goes into safe mode, it will remain in that state until the main branch is longer than the attack chain by the number of block specified by the configurable parameter safemodeminblockdifference (defaults to 72 blocks).

Safe mode can be disabled (RPC functionality restored) by putting the disablesafemode configuration parameter to 1 and restarting the node. It is recommended that this is NOT done, except in extreme circumstances. If this option is set, the node becomes vulnerable to Withholding attacks.

General Idea

Your business should be able to validate the transactions it receives without having to keep all block data and validate every transaction to ever have existed.

You can achieve this by listening to block announcements from peers on the bitcoin network, inspecting each header to verify that it contains a reference to the last, forming a hash chain back to the well-known genesis block.

Third parties need only send you:

• A transaction

• A Merkle path connecting that transaction to a particular block header

With that data alone you can validate the transaction. First you hash it, and run a Merkle proof to get the root hash. If that Merkle root is contained in the block header at the specified height then the transaction is proven to be contained in that block.

Extrapolation

You may have noticed that in the above scenario, the transaction had been broadcast in advance.

For small casual payments we need to be able to run SPV without either party waiting for a transaction to be mined first. This is possible by extrapolating the idea. We stipulate that the sender must include:

• A transaction

• Each transaction which contains an output we are spending in the new transaction.

• A Merkle path for each of those input transactions.

It is possible to iterate this recursively so long as every transaction always has parent transactions or a Merkle path associated with it.

With this extrapolated approach, we must also validate each transaction which doesn't have a Merkle path. The validation should confirm that the unlocking scripts evaluate to TRUE, the satoshi amounts are as expected, and the transaction is generally well formed without error. This way we know that when we broadcast it will be accepted by the nodes.

Common Push Back

"How do you know that the outputs in question haven't been spent already elsewhere?"

What we are able to factually determine is that the scripts all evaluate to TRUE, the satoshi amounts are all as expected, the structure of the transaction is valid, and that the sender (at least at one point) owned the outputs being spent. What we cannot know without broadcasting the transaction to miners is whether the outputs have been spent by another transaction already.

Rebuttal

It is a good question, but misses the point:

1. There is a high cost to faking this data because a hypothetical scammer would have to create genuine spendable outputs with which to attempt to trick someone.

2. The recipient would find out within a fraction of a second of broadcast if the tx is a double spend attempt. Nodes have callback services for this exact purpose.

3. The recipient would then have signed evidence that the counterparty they were doing business with attempted to defraud them.

4. Payments are negotiated after KYC and AML checks have been completed by each counterparty, so prosecution would be trivial.

In conclusion - SPV works for the same reason Bitcoin itself works - the incentive models guide the behavior of participants.

What is it?

• Open Source Non-Custodial Hosted Wallet

• Compatible with Existing BSV Ecosystem

• Reference Implementation for Simplified Payment Verification

• Maintained by the BSV Association

• 100x Cheaper to run than a node

SPV Wallet is an open-source, non-custodial hosted wallet that seamlessly integrates with the existing BSV Blockchain ecosystem. It serves as a reference implementation for Simplified Payment Verification, ensuring a secure, efficient, and user-friendly experience.

Developed and maintained by the BSV Association, SPV Wallet is designed to be cost-effective and accessible. It is 100x cheaper to run than a full node, making it an ideal solution for businesses who want to participate in the BSV network without being miners themselves.

In the following sections, we will delve into the technical details of SPV, explain how it works, and provide step-by-step instructions for setting up and using the wallet. Join us on this journey as we explore the future of Bitcoin SV with SPV Wallet, and discover a new way to manage your digital assets securely and efficiently.

Benefits

Secure

Scalable

Cost Savings

Legal

"LiteClient" has been replaced by "SPV Wallet"

Timestamp Server

BSV uses a distributed timestamp server to create a public record of transactions. This is achieved by hashing transactions into an ongoing chain, forming a record that is computationally impractical to alter. Each timestamp includes the previous timestamp in its hash, forming a chain of blocks, or a “blockchain.”

Proof of Work

To maintain this chain, BSV uses a proof-of-work system. Nodes, which are essentially powerful computers, compete to solve complex mathematical problems. Solving these problems involves finding a hash value that meets certain criteria (e.g., begins with a specific number of zero bits). The first node to find a valid solution broadcasts its block to the network.

Block Creation and Verification

When a node finds a valid proof-of-work, it broadcasts the block to all other nodes. These nodes verify the block to ensure all transactions are valid and not already spent. Once verified, the new block is added to the chain, and the nodes begin working on the next block, using the hash of the previous block as a reference.

Chain of Proof

The longest chain of blocks represents the sequence of events witnessed by the network. This chain is considered the correct one because it has the most proof-of-work effort invested in it. If nodes control the majority of CPU power and act honestly, they will create the longest chain and outpace any attackers trying to alter past transactions.

Immutability and Security

Once a block is added to the blockchain, altering it would require redoing the proof-of-work for that block and all subsequent blocks, which is computationally infeasible if the network’s honest nodes control the majority of the hash power. This ensures the immutability and security of the transaction history.

Decentralized Consensus

The network reaches consensus without a central authority. Each node operates independently, validating transactions and blocks. Nodes follow the longest chain rule, where they consider the longest valid chain as the true record of transactions.

This system ensures that transactions are timestamped and recorded in a secure, decentralized manner, allowing for an immutable and verifiable history of events on the BSV blockchain. The reliance on proof-of-work and the decentralized nature of the network are key factors that enable BSV to function effectively as a timestamp server.

A Merkle tree (or hash tree) is a data structure used in computer science and cryptography to efficiently and securely verify the integrity of large sets of data. It is a binary tree where each leaf node is a hash of a block of data, and each non-leaf node is a hash of its children.

To get from a leaf node (such as a transaction ID, txid) to the root in a Merkle tree, you follow these steps:

1.	Identify the Leaf Node: Start with the hash of the transaction (txid) you are interested in. This is your leaf node.
2.	Sibling Hash: Find the hash of the sibling node. If your leaf node is the left child, the sibling is the right child, and vice versa.
3.	Parent Hash: Concatenate the hash of your leaf node with the hash of its sibling. Then, hash this concatenated value to get the hash of the parent node.
4.	Repeat Up the Tree: Move up the tree by repeating steps 2 and 3. For each parent node, find its sibling, concatenate their hashes, and hash the result to get the next parent node.
5.	Reach the Root: Continue this process until you reach the top of the tree, which is the root hash.

Using a Merkle Tree rather than simply hashing the list of transaction IDs (txids) offers several advantages:

1.	Efficient Verification: Merkle Trees allow efficient and secure verification of the integrity of the data. With a Merkle Tree, you only need to check a small number of hashes (the Merkle path) to verify that a specific transaction is included in the set. This is much more efficient than checking all txids in a list.
2.	Partial Validation: Merkle Trees enable partial validation, meaning you can verify individual transactions without having to download the entire set of transactions. This is particularly useful in distributed systems like blockchain, where nodes can validate transactions without needing the entire blockchain.
3.	Scalability: Merkle Trees scale well with the number of transactions. As the number of transactions grows, the depth of the tree increases logarithmically, keeping the number of operations needed for verification manageable.
4.	Fault Tolerance: Merkle Trees provide a way to identify and isolate data corruption or tampering. If a hash in the tree does not match, it indicates the presence of a corrupted or tampered transaction, and the tree structure helps pinpoint the exact location of the issue.
5.	Efficient Storage and Bandwidth: In systems where data needs to be transmitted over a network, using Merkle Trees can reduce the amount of data that needs to be sent. Only the relevant Merkle paths are needed for verification rather than the entire list of transactions.

The following directions will walk you through creating a Bitcoin SV node within GKE (Google Kubernetes Engine).

If you wish to run another version of bitcoind, just change the image reference in bitcoin-deployment.yml.

Steps:

1 - Add a new blank disk on GCE called bitcoin-data that is 200GB. You can always expand it later.
2 - Save the following code snippets and place them in a new directory kube.
3 - Change the rpcuser and rpcpass values in bitcoin-secrets.yml. They are base64 encoded. To base64 a string, just run echo -n SOMESTRING | base64.
4 - Run kubectl create -f /path/to/kube
5 - Profit!

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  namespace: default
  labels:
    service: bitcoin
  name: bitcoin
spec:
  strategy:
    type: Recreate
  replicas: 1
  template:
    metadata:
      labels:
        service: bitcoin
    spec:
      containers:
      - env:
        - name: BITCOIN_RPC_USER
          valueFrom:
            secretKeyRef:
              name: bitcoin
              key: rpcuser
        - name: BITCOIN_RPC_PASSWORD
          valueFrom:
            secretKeyRef:
              name: bitcoin
              key: rpcpass
        image: bitcoinsv/bitcoin-sv
        name: bitcoin
        volumeMounts:
          - mountPath: /data
            name: bitcoin-data
        resources:
          requests:
            memory: "2Gi"
      restartPolicy: Always
      volumes:
        - name: bitcoin-data
          gcePersistentDisk:
            pdName: bitcoin-data
            fsType: ext4

Warnings in the log file are provided for informational and diagnostic purposes (e.g. needed to help with debugging). They do not necessarily indicate that corrective action needs to be taken. None of the warnings below require corrective action.

Failed to open mempool file from disk.
Continuing with empty mempool and transaction database

The mempool could not be synced at startup, typically as a result of improper shutdown (e.g. OOM). In this case the node will start with an empty mempool and request missing transactions.

Messages regarding misbehaving peers...

Banning misbehaving peers is an important part of normal operation. BCH nodes often appear as misbehaving nodes.

Found invalid chain at least ~6 blocks longer than our best chain

The 'invalid chain' message above indicates that there is a fork where the competing chains differ in length by at least 6 blocks.

Forks emerge naturally as competing blocks from different miners arrive at different nodes at different times. However the network will eventually agree on the best chain.

Forks can also arise from Withholding attacks which generally generate forks (secretly produced without announcing them at first) that are much longer than those that arising as a result of normal competition amongst miners.

The network does not agree...

Occasionally different nodes will have different best chaintips and these differing blocks will have the same parent block. The consensus mechanism will take care that the longer best chain will prevail.

The “standard” version of a block header is 02000000 but most miners use ASICBoost which uses extra bytes in the version field as a nonce.

Included in this repo are docker images for the Bitcoin SV Node implementation. Thanks to Josh Ellithorpe and his repository, which provided the base for this repo.

This Docker image provides bitcoind, bitcoin-cli and bitcoin-tx which can be used to run and interact with a Bitcoin server.

To see the available versions/tags, please visit the Docker Hub page.

To run the latest version of Bitcoin SV:

docker run bitcoinsv/bitcoin-sv

To run a container in the background, pass the -d option to docker run, and give your container a name for easy reference later:

docker run -d --rm --name bitcoind bitcoinsv/bitcoin-sv

Once you have the bitcoind service running in the background, you can show running containers:

Or view the logs of a service:

To stop and restart a running container:

The best method to configure the server is to pass arguments to the bitcoind command. For example, to run Bitcoin SV on the testnet:

Alternatively, you can edit the bitcoin.conf file which is generated in your data directory (see below).

By default, Docker will create ephemeral containers. That is, the blockchain data will not be persisted, and you will need to sync the blockchain from scratch each time you launch a container.

To keep your blockchain data between container restarts or upgrades, simply add the -v option to create a :

Alternatively, you can map the data volume to a location on your host:

By default, Docker runs all containers on a private bridge network. This means that you are unable to access the RPC port (8332) necessary to run bitcoin-cli commands.

There are several methods to run bitcoin-cli against a running bitcoind container. The easiest is to simply let your bitcoin-cli container share networking with your bitcoind container:

If you plan on exposing the RPC port to multiple containers (for example, if you are developing an application which communicates with the RPC port directly), you probably want to consider creating a user-defined network. You can then use this network for both your bitcoind and bitclin-cli containers, passing -rpcconnect to specify the hostname of your bitcoind container:

There are two main data models used in SPV transactions. Firstly, the Merkle paths of transactions are contained

Secondly a list of BUMPs and transactions are serialized:

These formats are baked in to the ecosystem's core libraries such that they are easy to deal with across many applications.

Transactions

• Transaction Relay

• Block Inclusion Fee

Blocks

Others

regtest is a private “regression” test network, meant for local testing.

There are no seed servers for this network and all nodes need to be manually connected. regtest is used by the node’s functional test suite.

By default:

• Uses port 18332 for RPC

• Uses port 18444 for P2P

Getting Started

This section assumes that you have installed bitcoind, the BSV server software. If not, Instructions can be found here: .

The network environment used by a node is configurable. To select regtest,

• add "-regtest=1" as a parameter on the command line, or

• add "regtest=1" to the node's configuration file (./bitcoin/bitcoin.conf).

Funding

The difficulty in regtest is near zero so it is relatively easy to mine blocks to obtain funds and many test scripts to that.

Make sure that you are operating in regtest. The following command can be used to generate a new address to receive funds.

The following command will mine regtest for 101 new blocks and send the funds to the generated address.

You need to mine a further 100 blocks before the funds from mining a block can be spent.

The bitcoin-data folder will contain the logs, blocks, UTXO set (stored in chainstate) and various other files the SV Node needs to function. For mainnet this folder will get very big, around 350GB for the UTXO set and 12TB for the blocks as of January 2024. The UTXO set is used for lookups to validate transactions and should be stored on a high-performant SSD. Depending on your use case, the blocks can be stored on slower, cheaper HDD storage.

If setting up the node in AWS, the recommendation is to use an instance type with strong single threaded performance like r7i and mount 1 or more EBS volumes of sc1 type for the bitcoin-data/blocks folder and use an EBS mounted io2 for the bitcoin-data folder including the chainstate.

For the blocks mount, it is recommended to use LVM to get around the AWS limitation of 16TB per volume, this will be needed as the blocks folder will continue to grow over time.

For io2 be mindful of the pricing: a 500GB disk with 3000 IOPS is $260 per month, a 500GB disk with 64000 IOPS is $3600 per month. 3000 IOPS should suffice, the main advantage io2 will bring is improved latency.

Installation

These commands assume the larger, slower storage is at /dev/nvme1n1 and the fast storage is at /dev/nvme2n1

Step 1: Install LVM2

Step 2: Prepare Physical Volume

Create LVM physical volumes the slower storage:

Step 3: Create a Volume Group

Create a volume group including the relevant devices:

Step 4: Format and Mount the Logical Volume

Format the cached logical volume and mount it:

Step 5: Format and Mount the SSD volume

Format the SSD volume and mount it:

Step 6: Create the symlinks

Step 7: Automount on Startup

Edit /etc/fstab to automount the logical volume on startup:

1. Get the UUID:

2. Add to /etc/fstab (replace <your-UUID> with the actual UUIDs):

Step 9: Testing the Configuration

Reboot your system and test the configuration:

After rebooting, verify the setup:

A full initial Block Download can take a long time depending on your setup. For reference, a full initial block download on an AWS r7i.8xlarge instance with 256GB RAM, configured with Installation docs and the AWS Volumes Setup takes around 6 days as of Feb 2024. After the IBD you can downgrade the instance to r7i.4xlarge with 128GB RAM, depending on network load and what the node will be used for.

Unable to complete Initial Block Download

See github.com/bitcoin-sv/bitcoin-sv/wiki/Block-download-issues Most issues related to stuck blocks and IBD (Initial Block Downloads) are the result of insufficiently powerful system, i.e. not enough available disk space or memory or configuration issues.

Configuration

Check that excessiveblocksize is up-to-date (current recommendation is 10GB = 10000000000). If a block is in excess of the excessiveblocksize, the node will regard the block as invalid and it will not be added to the blockchain.

I.e. Blocks arriving over the network larger than the specified size with be rejected and the blockchain will stall. An IBD (Initial Block Download) will not progress passed this block.

The following log message is emitted under this condition:

Note that this is a generic log entry for oversized messages.

Inadequate Network Performance

The block has a hard-coded timeout for block downloads (10 mins). If a block cannot be downloaded in that time, the download times out and fails.

A 4GB block requires both the source server and the network to sustain at least 56MB per second per connection. On rare occasions a new block may not found for 30 minutes or more. In that case, the size of the block will be roughly 3x the size of a standard block. If 4GB blocks become the norm, the source server and network may need to sustain at least 168MB per second per connection. If your system does not meet that requirement, your node may timeout during IBD.

The parameter blockdownloadtimeoutbasepercent can be used to extend the downloading time. The parameter specifies the new timeout as a percentage of 10 minutes.

Docker Issues

Docker container memory limits have been responsible for slow IBD. If a large block arrives, the limit may be reached and the process killed.

Insufficient Disk Space

On some systems, during IBD the thread downloading the blocks may race ahead of validation, and as a result the amount of blocks on disk may exceed the prune setting if there is one.

Insufficient Memory

Under some circumstances the processing of a single incoming block may produce a short-lived memory usage spike (up to 3x the size of the block).

If your node crashes and does not produce a core dump (even though configured to do so), check /var/log/syslog to see if the process ran out of memory and was terminated by the OS.

Using the loadblock to resolve download issues

If you have access to another working node and your download fails at a specific block height, it may be a good idea to copy the blkXXXXX.dat file for the specific block across to you local block repository and use the loadblock configuration option to get the node to load the version of the block stored locally on disk rather than perform a download over the network. Make sure the originating node is using the same preferredblockfilesize value.

Note that you need to ensure that you trust the source of your blkXXXXX.dat files. See bitcoind help for more information.

Background to the Rules

Part I - Master Rules

1. The Rules in overview

2. Agreement to the Rules

3. Network Activities and Block Reward

4. Network access criteria

5. Node responsibilities

6. Node acknowledgements

7. Nodes’ individual and collective obligations

8. Liability

9. Suspension

10. Governing law

1. Affiliates

2. The relationship of the parties

3. Entire agreement

4. No implied terms

1. Directives

2. Nodes’ obligation to follow Directives

3. Enforcement Event

4. Direct Decision Event

1. Arbitration

2. Binding nature

3. Changes

1. Principles of interpretation

2. Glossary

Getting Started with Bitcoin STN

This guide will help you in setting up a BitcoinSV node which connects to the Scaling Test Network.

What is STN?

The STN is a public test network targeted at testing scaling. Block sizes are typically bigger than those on mainnet, but transaction volumes are generally much lower. It is not uncommon for performance/capacity tests to be run in STN, in which case transactions per second can rise dramatically. New blocks/coins are generated using CPU mining. The STN blockchain may also be “reset” for a new node releases. I.e. the blockchain is wound back to a previous height to minimise start-up times for new nodes.

System requirements for running a STN node:

More information about STN can be found on

QuickStart Instructions

Step 1:

Install SV Node according to the installation guide:

Step 2:

Configure bitcoind to connect to the STN and not Mainnet, as well as setting mandatory parameters. Make the following changes to your bitcoin.conf

Step 3:

If you wish to add any other custom configurations to your Bitcoin SV node you can appended them to the bitcoin.conf file with the editor of your choice. If you are running a node for development and not archival purposes it is recommended you operate in prune mode to prevent excessive disk space usage. Make the following change to your bitcoin.conf.

Step 4:

Start the bitcoind process. If you have been following the installation guide you can use systemd

If this is the first time you have started the node, it may take several hours or even days as the node downloads blocks and checks that they have not been tampered with. In this case, it may make sense to run the node in foreground to see status messages.

If this is not the first time you have run the node, it should start up quickly and it may make sense to run the node in the background.

Step 5:

Check the status of the node and the bitcoind process. Type the following at the command line:

This should generate an output similar to

Funding

If you wish to perform worthwhile testing in the STN you need to obtain unspent coins. Unspent coins may be obtained from the STN team by contacting on Telegram. Alternatively it is possible to mine coins as the difficulty in STN is low and mining should only take a few minutes using a laptop.

Complete stand-alone server using the SPV Wallet engine to manage xpubs, utxos, destinations, paymails and transactions. It's non-custodial wallet, which means that it doesn't store any private keys.

Table of Contents

1. Quick Start

SPV and BEEF

SPV Wallet can do SPV and work with BEEF transactions, you can read more about it in below documents.

Important Concepts

BUMP, BEEF and SPV

SPV Wallet work with BUMP Merkle Proof format, which is a way to prove that transaction is included in the block.

After broadcasting or receiving a transaction, SPV Wallet will query Arc API (or wait for a callback) to get BUMP for the transaction. Having BUMP on any level of ancestry for all inputs of the transaction, allows us to send it to the network.

By having this information we can easily verify all merkle proofs which is a part of SPV protocol.

To verify merkleroots we need to have a block headers service running. More about BUMP you can read .

Useful links:

SPV Wallet HTTP Server

SPV Wallet exposes an HTTP server which allows you to interact with database, manage xpubs, paymails and work with transactions. It's a complete stand-alone server using the SPV Wallet engine.

API Documentation can be found in swagger - you can access it by running SPV Wallet and going to http://localhost:3003/swagger/index.html.

SPV Wallet Clients

We strongly encourage you to use one of the SPV Wallet client libraries provided for different languages, which are abstracting out http connection and handle authentication for you:

Block Headers Service runs as part of the SPV Wallet, you do not need to deploy it separately. If you want to run it without the rest of the stack, deployment instructions can be found in the README of the repository in Github.

Integration of Block Headers Service

One significant step in the evolution of the SPV Wallet is the integration of Block Headers Service. Block Headers Service listens to block announcements from mining nodes on the p2p network, requests the block headers, and validates them on receipt to ensure they're part of the longest chain of work. It independently maintains a full history of all block headers, and exposes them via a secure web API. SPV Wallets can use this API to validate the inclusion of a transaction within a particular block. This is a critical component of SPV functionality, as it allows confirmation of transactions without downloading the entire blockchain.

Example Application integrated with SPV Wallet

The frontend web wallet application allows users to register, make transactions, and see their balance. This is what we'd expect you to replace with your own application front end, but is included in the deployment to provide a working demo for basic payment functionality.

Front End

Back End

The backend API is coupled with the web wallet, and demonstrates use of the Wallet Client library.

Clients

The client libraries themselves are available separately such that integrating with your own front end should be straightforward.

Golang

JavaScript

Table of contents

• Overview

• Installation

Overview

This is TypeScript / JavaScript library used to communicate with SPV Wallet. It allows to create an admin or normal user client and then call methods to work with transactions, xpubs, paymails and access keys.

Installation

NPM

Yarn

User / Wallet / Account creation

To create a new user (which some may also interpret as creating a wallet or account), you need to register a new xPub. You can find example of how to do that .

Authentication

To authenticate within the SPV Wallet, you need to use HD key pair either for admin or normal user. Detailed instruction on how to authenticate the client can be found .

Examples

We have prepared some examples for you to get started with the library. All of them are available on the SPV Wallet Client GitHub repository, in the directory.

What is Web3?

• Shift from pure computer networks to semantic networks

• Individual devices maintin their own state (could be cloud, local, or hybrid)

The system known as "type-42," based on the BRC-42 technical standard introduces a sophisticated method of key derivation that enhances privacy and enables what are known as "private signatures." This document aims to elucidate the principles of type-42 derivation, demonstrate its role in enabling private signatures, and explore its broader implications within the BSV ecosystem.

Understanding Key Derivation

Before delving into the specifics of type-42, it is essential to understand the concept of key derivation in cryptographic systems. Key derivation is a process that generates one or more keys from a single master key, which can then be used for various cryptographic purposes, such as encryption, decryption, and digital signing. Traditional key derivation methods like BIP32 offer limited flexibility and privacy because they restrict the number of derivable keys and allow anyone to see all the derived children, even those computed by others.

Alert System

Version 1.1 reintroduces the Alert System. The Alert System, originally implemented in the v0.3.10 Bitcoin release, enables the BSV Association to send signed messages to the network. Messages can be of an informational or directive nature. This release also contains native support for Digital Asset Recovery alerts. Alongside the release of the Alert System, the BSV Association has released the Network Access Rules of the BSV network. The Network Access Rules specify the terms and conditions by which nodes (miners) in the BSV network operate. As stated in the Network Access Rules, it is expected that all nodes in the network process validly signed Alert Messages broadcast to the network. The Network Access Rules can be read in their entirety here:

The Alert System connects to other nodes using the libp2p protocol, the same peer to peer protocol that will be used in Teranode, and is currently used in IPFS. Libp2p is a modular system of protocols, specifications, and libraries that enable the development of peer-to-peer network applications. The Alert System uses a distributed publish/subscribe (pubsub) mechanism for communication. Alert Generator – the alert publisher – sends an alert to a predefined topic. To receive a published alert, all the Alert System nodes – the alert receivers –subscribe to that topic. The following topics are used for communication:\

A SIGHASH flag is used to indicate which part of the transaction is signed by the ECDSA signature. The mechanism provides a flexibility in constructing transactions. There are in total 6 different flag combinations that can be added to a digital signature in a transaction. Note that different inputs can use different SIGHASH flags enabling complex compositions of spending conditions.

NOTE: Currently all BitcoinSV transactions require an additional SIGHASH flag called SIGHASH_FORKID which is 0x40

The tables below illustrate what is signed and what is not signed in an ECDSA siganture depending on the SIGHASH type used.

Items that are always signed

The signature on any input always signs the and that comprise the Outpoint being spent as well as the of the protocol that the transaction is being evaluated under and the being applied to the transaction.

Items that are never signed

Unlocking scripts are never signed

SIGHASH_ALL

SIGHASH_ALL signs all inputs and outputs used to build the transaction. Once an input signed with SIGHASH_ALL is added to a transaction, the transaction's details cannot be changed without that signature being invalidated.

SIGHASH_SINGLE

SIGHASH_SINGLE signs all inputs and the output that shares the same index as the input being signed. If that output or any inputs are changed that signature becomes invalidated.

SIGHASH_NONE

SIGHASH_NONE signs all inputs and no outputs. Any output can be changed without invalidating the signature however if any inputs are changed that signature becomes invalidated.

SIGHASH_ALL|ANYONECANPAY

`Once an input signed with SIGHASH_ALL|ANYONECANPAY is added to a transaction outputs cannot be changed or added without that signature being invalidated.

SIGHASH_SINGLE|ANYONECANPAY

SIGHASH_SINGLE|ANYONECANPAY signs the input being signed and the output that shares the same index. If that output is changed that signature becomes invalidated.

SIGHASH_NONE|ANYONECANPAY

SIGHASH_NONE|ANYONECANPAY signs a single inputs and no outputs. This type of signature can be used to easily assign funds to a person or smart-contract without creating an on-chain action.

Use cases

SIGHASH flags are useful when constructing smart contracts and negotiable transactions in payment channels.

Use Case 1 - Crowdfunding

Using ALL | ANYONECANPAY allows a transaction to have a fixed output or fixed outputs while keeping the input list open. That is, anyone can add their input with their signature to the transaction without invalidating all existing signatures.

Use Case 2 - Blank Check

Using NONE allows anyone to add their desired outputs to the transaction to claim the funds in the input.

Use Case 3 - Modular Transaction

Using SINGLE | ANYONECANPAY modularises a transaction. Any number of these transactions can be combined into one transaction.

PART III - ENFORCEMENT RULES

1. Directives

   1. Subject to clause III.6, the Association may in its absolute discretion issue a direction to a Node requiring it to take a Step or Steps (a ‘Directive’) where there is:

      • (a) an Enforcement Event;

      • (b) a Direct Decision Event; or

      • (c) an Indirect Decision Event.

   2. In the Rules, the term ‘Directive Event’ refers to any of the events in clause III.1.1. These Directive Events are defined below.

2. Nodes’ obligation to follow Directives

   1. Subject to clauses III.6 and III.2.2, each Node will promptly comply with the requirements of any Directive applicable to it following receipt of notice of the Directive and in any event no later than any time for compliance which is specified in the notice of the Directive.

   2. Any Directive will take effect immediately upon notice to a Node or Nodes unless otherwise expressly stated in the notice of the Directive.

3. Enforcement Event

   1. An ‘Enforcement Event’ occurs in respect of any one or more Nodes when the Association reasonably determines in good faith that one or both of the following has occurred:

      1. (a) a breach by the relevant Node(s) of any of Part I of the Rules (Master Rules), clause II.1 (Affiliates), clause II.7 (Indemnity), or clause III.2 of these Rules; or

      2. (b) any representation or warranty in the Rules given by the relevant Node(s) is false or misleading when made, repeated, or deemed to have been made or repeated.

4. Direct Decision Event

   1. A ‘Direct Decision Event’ occurs when the Association receives a Decision that the Association reasonably determines in good faith is a Direct Decision.

   2. A ‘Direct Decision’ is a Decision that:

      • (a) has the force of law, has been recognised, or is enforceable in England and Wales or Switzerland;
5. Indirect Decision Event

   1. An ‘Indirect Decision Event’ occurs when the Association receives a Decision which the Association reasonably determines in good faith is an Indirect Decision.

   2. An ‘Indirect Decision’ is a Decision that:

      • (a) has the force of law, has been recognised, or is enforceable in England and Wales or Switzerland;
6. Restrictions on Directives

   1. The Association may not issue a Directive where there has been no Directive Event.

   2. A Directive may only require a Node or Nodes to do any or all of the following steps (each a ‘Step’):

      • (a) freeze specified coins in unspent transaction outputs;

1. Information obligations

   1. Each Node agrees that it will notify the Association promptly of any circumstances which are reasonably likely to give rise to a Directive Event.

   2. Each Node agrees that, on demand by the Association, it will promptly provide the Association with any information the Association may reasonably request in connection with the Rules or any Enforcement Event.

   3. Nothing in this clause III.7 requires a Node to disclose information where the disclosure by that Node would breach Applicable Laws.

The main BSV GitHub is available here, showcasing all public repositories, enabling developers to contribute directly or use as the foundation for their own needs.

This page highlights the main repositories currently available on GitHub:

SDKs

The BSV Blockchain Libraries Project aims to structure and maintain a middleware layer of the BSV Blockchain technology stack. By facilitating the development and maintenance of core libraries, it serves as an essential toolkit for developers looking to build on the BSV Blockchain.

Three core libraries have been developed and made available:

• GO SDK:

  • Script templates:

• TypeScript SDK:

• Python SDK:

More information available

SPV Wallet

The SPV Wallet is a comprehensive non-custodial wallet for BSV, enabling Simplified Payment Verification (as described in the Bitcoin White Paper section 8).

The main repository is available under this link: .

Add-ons

In addition, the following repositories are related to SPV Wallets:

• Administrative console:

• TypeScript client:

• GO client:

• Web-Frontend:

More in-depth information and guidance about SPV Wallets is available

Block Headers Service

The Block Headers Service is a Go application used to collect and return information about blockchain headers.

ARC

ARC is a multi-layer transaction processor for BSV Blockchain that keeps track of the lifecycle of a transaction as it is processed by the network.

The main repository is available here:

Full details on ARC are not yet available in this BSV Skills Center, but can be found here:

SV Node

SV Node is the main node software used within BSV Blockchain. It is based on the original implementation of the Bitcoin protocol implemented as a monolith. The main repository is available here: For more details, see and the .

There is ongoing work for an improved and scalable microservice implementation of the node software (Teranode) to support a much larger network throughput of transaction processing. For more information, visit

Alert System

The Alert System must be run together with the SVNode software, to ensure that a node is able to receive alerts.

The main repository is available here:

Getting Started with Bitcoin testnet

This guide will help you in setting up a BitcoinSV node which connects to the testnet.

What is testnet?

Testnet is a public test network used for general testing. It is typically used to test software before it is released onto mainnet. As testnet is public and unmanaged, software on testnet may not be 100% stable. Transactions per second and block difficulty are low.

System requirements for running a Testnet node:

QuickStart Instructions

Step 1:

Install SV Node according to the installation guide:

Step 2:

Configure bitcoind to connect to the testnet and not Mainnet, as well as setting mandatory parameters. Make the following changes to your bitcoin.conf

Step 3:

If you wish to add any other custom configurations to your Bitcoin SV node you can appended them to the bitcoin.conf file with the editor of your choice.

Step 4:

Start the bitcoind process. If you have been following the installation guide you can use systemd

If this is the first time you have started the node, it may take several hours or even days as the node downloads blocks and checks that they have not been tampered with. In this case, it may make sense to run the node in foreground to see status messages.

If this is not the first time you have run the node, it should start up quickly and it may make sense to run the node in the background.

Step 5:

Check the status of the node and the bitcoind process. Type the following at the command line:

This should generate an output similar to

Funding

If you wish to use testnet for testing, you will need to obtain unspent coins. A number of faucets are available:

Size Matters

Storage gets really expensive when you have billions of transactions to store - just ask any miner.

The total cumulative size of all blockheaders is currently ~68MB. When comparing this to storing the whole blockchain, the advantage becomes obvious. The total size of the BSV blockchain at time of writing is over 10TB.

What's in a Block Header?

A block header is an 80 byte data structure which describes one block. As a hex string it looks like this:

Here's a breakdown of what all that means:

Example Block Header

0020372d395bfcfc03b467e747f873da7e4f4fd0afcc89301787b10a0000000000000000724ab3c241848b826766b46947e008e022b95877629498ec3e7dd85f1ae0b383f8f8826566280d184b11f02a

Previous Block Hash

The Previous Block Hash allows us to link the chain of blocks together all the way back to Genesis.

You might ask how do I know that the block header is valid if I don't have all the transactions? The easy way to detect fake block headers is to hash it, and if it doesn't have a bunch of zeros at the end then it is not legitimate. Creating a block header which hashes to a low number requires a boatload of ASIC machines iterating the nonce and hashing until a low output is found. Expensive to fake.

In MacOS Terminal we can copy paste the following to double sha256 the data and output the hash.

The result of which is below. See the bunch of zeros on the end? Seems legitimate.

Fake Block Header

Let's attempt to fake the Merkle Root to show how difficult it would be to get away with.

Again let's copy paste that into Terminal so that we can check the double sha256 block hash.

The result makes the forgery obvious, no zeros at the end.

If we fake this one block header and use some ASIC machines to hash it a bunch until we eventually get a low hash value, then we would need to do the same for every block header thereafter since they're all chained together. This quickly becomes infeasible.

Merkle Root

The Merkle Root is what we compare to the calculated value we get from our txid and Merkle Path. If it matches, then we have definitive proof that the transaction was indeed included within the block with that header.

Disclaimer

The content of this document is provided for informational purposes only and is not intended to modify or supersede the contractual rights or obligations of any party to the Network Access Rules. Parties are encouraged to carefully review the Network Access Rules to verify the accuracy of the information presented here. It is assumed that, where necessary, parties will seek guidance from their legal counsel and any other advisors they consider necessary.

Any statements here do not purport and should not be considered to be a guide to, advice on, or explanation of all relevant issues or considerations relating to the contractual relationship established by the NAR. The BSV Association assumes no responsibility for any use to which the BSV network is put by any miner or other third party.

Definition

An overlay in computer networking refers to a virtual network built on top of an existing physical network. It augments or extends the underlay, providing services like routing, peer-to-peer networking, or distributed computing. In BSV, overlays operate on the BSV Node Network, offering services like transaction lookups, token management, and open predicates.

Overlays a Glance

Global Listening is the typical historical way Blockchains have gathered transactions so that they can be indexed and read back by client applications.

Overlays encapsulate a different approach. They rely on to validate transactions they receive from clients, and allow users to read transaction data back without having to index all block data.\

Business Context

Current BSV applications often rely on reading timestamped immutable data from the blockchain, which is not feasible at high transaction volumes without Simplified Payment Verification (SPV) and the division of labor. Overlays distribute demand for immutable data across many services, enabling businesses to minimize waste and select services based on their needs and costs.

Features of an Overlay

Overlays ingest and validate transactions using SPV, maintain the valid chain of headers, submit valid transactions to the BSV Node Network, and maintain transaction propagation status. They also acquire and distribute Merkle paths for mined transactions, sync with peers, and optionally expose UTXO and transaction lookups.

Infrastructure Dependencies

Overlays depend on the BSV Node Network for new header announcements, a Merkle Service for calculating Merkle paths, and widespread use of SPV data structures within wallets and applications. They provide a cost-effective, scalable, and secure solution for businesses by ensuring data integrity and network resilience.

User Types

Overlays cater to various users including:

• Private Overlays: For specific individuals or businesses.

• Public Overlays: For developers without infrastructure, like .

• Ring Fenced Overlays: For financial institutions with jurisdictional restrictions.

• Open Protocol Overlays: For experimental applications by entrepreneurial developers.

Use-Cases

Overlays have diverse use-cases across industries such as:

• Event and Airline Ticketing

• Cloud Storage and eCommerce

• Central Banks for Digital Currencies

• Token Protocols: Specific transaction types for tokens like STAS and Tokenized.

• Wallet Providers: For providers like Handcash, Centbee, and RockWallet.

• Fungible Tokens (FTs): For CBDCs, PIDMs, stable coins, etc.

• Non-Fungible Tokens (NFTs): For hotel keys, allocated gold, etc.

• Open Predicates (OPs): For computation markets.

• Data Predicates (DPs): For storage markets.

• Backup Services: For transaction and metadata recovery.

• Explorers: For development, receipts, or status checks.

Technical Components

Web API

Exposes endpoints for submitting transactions and looking up transactions by ID.

Store

Maintains transactions, UTXOs, headers, Merkle paths, and metadata.

Validator

Runs SPV and additional business logic.

Listener

Monitors headers, alerts, and transaction rejections.

Synchronizer

Syncs state with other overlay nodes.

Path Confirmer

Requests Merkle proofs for unconfirmed transactions.

Architecture

What we have today looks something like this:

Future Outlook

The future of overlay networks includes advancements in scalability, security, and regulatory compliance, positioning BSV as a leading platform for various industries.

Technical Changes

We expect there to be a scaled Merkle Service which will replace ARC's microservice BlockTx as the component which calculates Merkle paths. This change is anticipated because Teranode blocks can get siginificantly bigger, and BlockTx is not built for anything larger than 4GB blocks. Teranode announces subtrees while constructing its own block, so the work can start early and propagation can be executed on block discovery without there being a massive spike in computational effort at that moment only to be left unused until a new block is found. The work is instead distributed over the duration of the block assembly process. More on that as alpha versions are released.

Block Downloads Fail

Generally issues that effect block downloads (e.g. getblock) are the same as those effecting IBD (Initial Block Download). See Initial Block Download for more details.

Block Hex Dump fails

The RPC-function getblock does not work for some big blocks. In some cases, getblock returns an incorrect content and hex-dump size.

The workaround is to use the REST interface. See .

Enable the REST interface by adding rest=1 in the config file, or -rest on the command line.

Pruning Overview

The first time a node is run, it downloads all the blocks in the BSV blockchain (which starts with the original BTC Genesis block). The Initial Block Download (IBD) can be time consuming and take a number of days, however the process cannot be cut short. Downloading and validating the blocks (which includes validating the transactions in the blocks) is the proof that the blockchain on disk was built up from the Genesis block using PoW, and is an unadulterated copy of the BSV blockchain.

The node disk storage requirements can be reduced by enabling pruning via the -prune configuration option. The node then attempts to keep storage below the specified value (in MB) by only keeping the newest blocks on disk. If manual pruning is enabled, the pruneblockchain RPC function can also be called to delete specific blocks.

The following points need to be considered:

• The node will keep at least 288 blocks no matter what the pruning settings is.

• txindex=1 on a pruned node is only possible in release 1.1.1+. If you attempt to request the details for a transaction that is in a block that has been pruned, then the node will simply return an error indicating that the transaction cannot be found.

• Pruning is disabled by default.

• There is no recommended value for

• If pruning is enabled, getdata and getblock RPC may fail as they may attempt to access a block that is no longer available. In that case, the error message looks like:

Arrival of New Blocks can make Node Unresponsive

The validation of a new arrived block is a high priority task since miners need to know if the new block is valid and whether they should continue to attempt to build on the current blockchain head or switch their resources to building on the new block. If the node mempools are in sync, then the node has already seen and validated the transactions in the new block and block validation can be very quick. If the node mempools are not in sync, which can happen if there is heavy traffic, the node will need to validate all the transactions it was not seen before. That can take some time (up to a minute). During that time the main SV node lock (cs_main) is held by block validation; without access to cs_main much of the other node functionality including the RPC interface is unavailable.

BCH and BTC Blocks

If a node connects to a non-BSV node, it may receive non-BSV blocks. That is not desirable but does not cause any fatal issues as the non-BSV blocks will not be successfully processed.

Diagnosis

Processing non-BSV blocks leaves characteristic messages in the log files. The following 'error' messages were the result of processing a BCH block on a BSV node.

and

To get information about connected nodes, type the following at the command line:

The node can be banned using the following command:

Prevention

SV nodes will refuse connections to non-BSV nodes based on the user agent in the version network message.

The banclieanua config option can be used to further filter node connections based on the user agent . For example:

Table of contents

• Overview

• Installation

Overview

This is GO library used to communicate with SPV Wallet. It allows us to create an admin or normal user client and then call methods to work with transactions, xpubs, paymails and access keys.

Installation

User / Wallet / Account creation

To create a new user (by some people also understand as creation of wallet or account), you need to register a new xPub. You can found example of how to do that .

Authentication

To authenticate within the SPV Wallet, you need to use HD key pair either for admin or normal user. Detailed instruction on how to authenticate the client can be found .

Examples

We have prepared some examples for you to get started with the library. All of them are available on the SPV Wallet Client GitHub repository, in the directory.

You can delete resources by deleting the CloudFormation stack.

All data within SPV Wallet will be deleted.

Manual delete is required for log groups.

Anyone interested in developing their own wallet can use this as a starting point. This is not only relevant for developers, but also for governments, enterprises and exchanges. The alignment of your software with this reference implementation will enable adoption of the latest industry standards, adapting to new BSV infrastructure as the network scales.

In order to develop your own applications based on this reference SPV Wallet implementation you'll need to fork the repositories individually.

Each component has its own README which will guide you through the setup process. A developer guide on how to get your dev environment set up and how each of the components works is here:

Below are the recommended system requirements based on our internal testing and scaling progress, made with bitcoind node software. Bitcoin SV will continue to scale on the road to, and beyond genesis. This will also mean these requirements should be expected to change as time goes on.

Overview

A UTXO-based system (Unspent Transaction Output) and an account-based system are two different methods of tracking ownership and transactions in blockchain networks.

Transaction Relay

Nodes are obliged to relay the transactions they receive to all other nodes that have outgoing connections to. This aims to ensure all nodes on the network are aware of all transactions submitted to the network, regardless of the mining fee they carry.

Block Inclusion Fee

The Genesis upgrade removes the default setting for the maximum block size and defines this as a “mandatory consensus parameter”. The upgrade also defines a new setting, the maximum script memory usage mandatory consensus parameter. The values for these parameters must be manually configured in the software by the system administrator. This page provides information on these parameters and recommendations on how to choose the required values.

The recommended method of choosing these parameters is to survey the major Bitcoin SV Miners and choose the same, or larger. It is expected that Miners will begin to publish these settings in their MinerID coinbase documents in the near future. However, in the meantime we will regularly update this page with known settings of various Miners manually.

We urge you to take note of the for running an instance of Bitcoin SV.

Maximum block size

The alert message format is standardized for all message types. Depending on the alert type, the message can vary in format.

Authenticate as admin

To authenticate within the SPV Wallet as an admin, you need to use admin HD key pair. At the SPV Wallet side the admin key pair is recognized by the admin xpub which need to be configured ().

When you have the admin xpriv, you can now create SPV Wallet Client for admin API:

Authenticate as admin

To authenticate within the SPV Wallet as an admin, you need to use admin HD key pair. At the SPV Wallet side the admin key pair is recognized by the admin xpub which need to be configured ().

When you have the admin xpriv, you can now create SPV Wallet Client for admin API: