Welcome to the Rust-based implementation of the Karlsen full-node and its ancillary libraries. This production release serves as a drop-in replacement to the established Golang node, introducing developers to the possibilities of Rust in the Karlsen network's context.
We invite developers and blockchain enthusiasts to collaborate, test, and optimize our Rust implementation. Each line of code here is an opportunity to contribute to the open-source blockchain movement, shaping a platform designed for scalability and speed without compromising on decentralization.
Your feedback, contributions, and issue reports will be integral to evolving this codebase from its Alpha phase into a mature and reliable node in the Karlsen network.
Karlsen is a fork of Kaspa introducing a GPU-centric fork as a solution to the dominance of ASIC mining farms, aiming to empower small-scale miners and enhance decentralization. We focus on bridging the gap between blockchain technology, decentralized finance and the real world of payment systems and traditional finance.
With Kaspa, our approach is one of friendly cohabitation. We operate under the same protocol, enjoy similar advantages, and face unidentified issues. Any significant improvements that need to be made in the primary codebase will be shared back.
The Karlsen Network team believes in decentralization and small-scale miners. We will ensure long-term GPU-friendly mining.
The Karlsen Network team is launching an R&D project to connect the Karlsen blockchain with other blockchain ecosystems using a smart contract layer based on the Cosmos SDK.
This initiative aims to enhance interoperability, efficiency, and innovation in the blockchain space. By leveraging the Cosmos SDK's advanced features, we'll facilitate seamless transactions across different networks, offering new opportunities for users and developers.
Cosmos is a highly attractive ecosystem due to its innovative approach to blockchain interoperability, scalability, and usability. By enabling different blockchains to seamlessly communicate and exchange value, Cosmos opens up vast opportunities for businesses and developers to build and deploy decentralized applications that can operate across multiple blockchain environments. This interoperability fosters a more connected and efficient digital economy, potentially driving adoption and usage across various sectors, including finance, supply chain, and beyond.
By connecting to Cosmos, we will open the door of a web3 ecosystem connected to a complete network of other blockchain project, making Karlsen Network more competitive and adaptable in the rapidly evolving landscape of decentralized technologies.
The creation of the Karlsen sidechain with fast transaction times, smart contract capabilities, and a dual coin model, designed to integrate seamlessly with the Cosmos ecosystem and utilize the Karlsen (KLS) across all interconnected platforms, signifies a strategic advancement in Karlsen Network.
This sidechain will not only enable quick and efficient inter-blockchain transactions but also support complex decentralized applications through its smart contract functionality.
The ability to use Karlsen (KLS) across the entire ecosystem will ensure a unified and streamlined user experience, promoting greater adoption and utility within the Cosmos network. This sidechain aims to enhance scalability, foster innovation, and provide a flexible and user-centric blockchain solution that meets the diverse needs of developers, users, and investors within the Cosmos ecosystem.
-
Install general prerequisites
sudo apt install curl git build-essential libssl-dev pkg-config
-
Install Protobuf (required for gRPC)
sudo apt install protobuf-compiler libprotobuf-dev #Required for gRPC
-
Install the clang toolchain (required for RocksDB and WASM secp256k1 builds)
sudo apt-get install clang-format clang-tidy \ clang-tools clang clangd libc++-dev \ libc++1 libc++abi-dev libc++abi1 \ libclang-dev libclang1 liblldb-dev \ libllvm-ocaml-dev libomp-dev libomp5 \ lld lldb llvm-dev llvm-runtime \ llvm python3-clang
-
Install the rust toolchain
If you already have rust installed, update it by running:
rustup update
-
Install wasm-pack
cargo install wasm-pack
-
Install wasm32 target
rustup target add wasm32-unknown-unknown
-
Clone the repo
git clone https://github.com/karlsen-network/rusty-karlsen cd rusty-karlsen
-
Install Git for Windows or an alternative Git distribution.
-
Install Protocol Buffers and add the
bin
directory to yourPath
-
Install LLVM-15.0.6-win64.exe
Add the
bin
directory of the LLVM installation (C:\Program Files\LLVM\bin
) to PATHSet
LIBCLANG_PATH
environment variable to point to thebin
directory as wellIMPORTANT: Due to C++ dependency configuration issues, LLVM
AR
installation on Windows may not function correctly when switching between WASM and native C++ code compilation (nativeRocksDB+secp256k1
vs WASM32 builds ofsecp256k1
). Unfortunately, manually settingAR
environment variable also confuses C++ build toolchain (it should not be set for native but should be set for WASM32 targets). Currently, the best way to address this, is as follows: after installing LLVM on Windows, go to the targetbin
installation directory and copy or renameLLVM_AR.exe
toAR.exe
. -
Install the rust toolchain
If you already have rust installed, update it by running:
rustup update
-
Install wasm-pack
cargo install wasm-pack
-
Install wasm32 target
rustup target add wasm32-unknown-unknown
-
Clone the repo
git clone https://github.com/karlsen-network/rusty-karlsen cd rusty-karlsen
-
Install Protobuf (required for gRPC)
brew install protobuf
-
Install llvm.
The default XCode installation of
llvm
does not support WASM build targets. To build WASM on MacOS you need to installllvm
from homebrew (at the time of writing, the llvm version for MacOS is 16.0.1).brew install llvm
NOTE: Homebrew can use different keg installation locations depending on your configuration. For example:
/opt/homebrew/opt/llvm
->/opt/homebrew/Cellar/llvm/16.0.1
/usr/local/Cellar/llvm/16.0.1
To determine the installation location you can use
brew list llvm
command and then modify the paths below accordingly:% brew list llvm /usr/local/Cellar/llvm/16.0.1/bin/FileCheck /usr/local/Cellar/llvm/16.0.1/bin/UnicodeNameMappingGenerator ...
If you have
/opt/homebrew/Cellar
, then you should be able to use/opt/homebrew/opt/llvm
.Add the following to your
~/.zshrc
file:export PATH="/opt/homebrew/opt/llvm/bin:$PATH" export LDFLAGS="-L/opt/homebrew/opt/llvm/lib" export CPPFLAGS="-I/opt/homebrew/opt/llvm/include" export AR=/opt/homebrew/opt/llvm/bin/llvm-ar
Reload the
~/.zshrc
filesource ~/.zshrc
-
Install the rust toolchain
If you already have rust installed, update it by running:
rustup update
-
Install wasm-pack
cargo install wasm-pack
-
Install wasm32 target
rustup target add wasm32-unknown-unknown
-
Clone the repo
git clone https://github.com/karlsen-network/rusty-karlsen cd rusty-karlsen
Rust WebAssembly (WASM) refers to the use of the Rust programming language to write code that can be compiled into WebAssembly, a binary instruction format that runs in web browsers and NodeJs. This allows for easy development using JavaScript and TypeScript programming languages while retaining the benefits of Rust.
WASM SDK components can be built from sources by running:
./build-release
- build a full release package (includes both release and debug builds for web and nodejs targets)./build-docs
- build TypeScript documentation./build-web
- release web build./build-web-dev
- development web build./build-nodejs
- release nodejs build./build-nodejs-dev
- development nodejs build
IMPORTANT: do not use dev
builds in production. They are
significantly larger, slower and include debug symbols.
- NodeJs (v20+): https://nodejs.org/en
- TypeDoc: https://typedoc.org/
- Release builds: https://github.com/karlsen-network/rusty-karlsen/releases
- Developer TypeScript documentation is available from Kaspa
karlsen-cli
crate provides cli-driven RPC interface to the node and
a terminal interface to the Rusty Karlsen Wallet runtime. These wallets
are compatible with WASM SDK Wallet API and Karlsen NG projects.
cd cli
cargo run --release
Run an http server inside of wallet/wasm/web
folder. If you don't
have once, you can use the following:
cd wallet/wasm/web
cargo install basic-http-server
basic-http-server
The basic-http-server will serve on port 4000 by default, so open your web browser and load http://localhost:4000
The framework is compatible with all major desktop and mobile browsers.
Start a mainnet node
cargo run --release --bin karlsend
Start a testnet node
cargo run --release --bin karlsend -- --testnet
Using a configuration file
cargo run --release --bin karlsend -- --configfile /path/to/configfile.toml
# or
cargo run --release --bin karlsend -- -C /path/to/configfile.toml
- The config file should be a list of <CLI argument> = <value> separated by newlines.
- Whitespace around the
=
is fine,arg=value
andarg = value
are both parsed correctly. - Values with special characters like
.
or=
will require quoting the value i.e <CLI argument> = "<value>". - Arguments with multiple values should be surrounded with brackets
like
addpeer = ["10.0.0.1", "1.2.3.4"]
.
For example:
testnet = true
utxoindex = false
disable-upnp = true
perf-metrics = true
appdir = "some-dir"
netsuffix = 11
addpeer = ["10.0.0.1", "1.2.3.4"]
Pass the --help
flag to view all possible arguments
cargo run --release --bin karlsend -- --help
wRPC subsystem is disabled by default in karlsend
and can be enabled
via:
JSON protocol:
--rpclisten-json = <interface:port>
Borsh protocol:
--rpclisten-borsh = <interface:port>
Rusty Karlsen integrates an optional wRPC subsystem. wRPC is a high-performance, platform-neutral, Rust-centric, WebSocket-framed RPC implementation that can use Borsh and JSON protocol encoding.
JSON protocol messaging is similar to JSON-RPC 1.0, but differs from the specification due to server-side notifications.
Borsh encoding is meant for inter-process communication. When using Borsh both client and server should be built from the same codebase.
JSON protocol is based on Karlsen data structures and is data-structure-version agnostic. You can connect to the JSON endpoint using any WebSocket library. Built-in RPC clients for JavaScript and TypeScript capable of running in web browsers and Node.js are available as a part of the Karlsen WASM framework.
wRPC to gRPC Proxy is deprecated and no longer supported.
Mining is currently supported only on testnet, so once you've setup a test node, follow these instructions.
-
Download and unzip the latest binaries bundle of karlsen-network/karlsend.
-
In a separate terminal run the karlsen-network/karlsend miner:
karlsenminer --testnet --miningaddr karlsentest:qrcqat6l9zcjsu7swnaztqzrv0s7hu04skpaezxk43y4etj8ncwfk308jlcew
This will create and feed a DAG with the miner getting block templates from the node and submitting them back when mined. The node processes and stores the blocks while applying all currently implemented logic. Execution can be stopped and resumed, the data is persisted in a database. You can replace the above mining address with your own address.
Logging in karlsend
and simpa
can be filtered
by either:
The current codebase supports a full in-process network simulation, building an actual DAG over virtual time with virtual delay and benchmarking validation time (following the simulation generation). To see the available commands
cargo run --release --bin simpa -- --help
The following command will run a simulation to produce 1000 blocks with communication delay of 2 seconds and 8 BPS (blocks per second) while attempting to fill each block with up to 200 transactions.
cargo run --release --bin simpa -- -t=200 -d=2 -b=8 -n=1000
Heap-profiling in karlsend
and simpa
can be done by enabling
heap
feature and profile using the --features
argument.
cargo run --bin karlsend --profile heap --features=heap
It will produce {bin-name}-heap.json
file in the root of the workdir,
that can be inspected by the dhat-viewer
Run unit and most integration tests
cd rusty-karlsen
cargo test --release
// or install nextest and run
Using nextest
cd rusty-karlsen
cargo nextest run --release
cd rusty-karlsen
cargo bench
Logging in karlsend
and simpa
can be filtered
by either:
-
Defining the environment variable
RUST_LOG
-
Adding the --loglevel argument like in the following example:
(cargo run --bin karlsend -- --loglevel info,karlsen_rpc_core=trace,karlsen_grpc_core=trace,consensus=trace,karlsen_core=trace) 2>&1 | tee ~/rusty-karlsen.log
In this command we set the
loglevel
toINFO
.