pippin-wallet 2.1.2

Description:

pippinwallet 2.1.2

Pippin is a production-ready, high-performance developer wallet for Nano and BANANO. Pippin's API is a drop-in replacement for the Nano developer wallet that is built in to the Nano node software.
About Pippin
Pippin is written in Python. It achieves high performance across the board using libraries such as asyncio, uvloop, aiohttp, asyncpg/aiosqlite/aiomysql, and rapidjson.
For block signing and work generation, Pippin uses nanopy, which is a high-performance library that utilizes C-bindings for blake2b and ed25519.
Benefits of Pippin
The Nano developer wallet (aka "node wallet") is not recommended for production use. One of the goals of Pippin is to provide a production-ready external key management that can be used by developers who are using Nano.
Pippin is the first drop-in replacement for the Nano developer wallet. It's incredibly easy to transition to Pippin if you are already using the Nano developer wallet.

Pippin is independent of the node. You can use Pippin with any public RPC, so you don't have to run your own node
Pippin is extremely fast and lightweight
Pippin supports encrypted secret keys
Pippin natively supports BPoW
Pippin supports multiple database backends (SQLite, PostgreSQL, and MySQL)

Pippin can be used by exchanges, games, payment processors, tip bots, faucets, casinos, and a lot more.
Pippin Performance

The benchmark script that was used is available here
There were 3 independent runs for each wallet, 62 blocks each, same node, and the same work peer. Pippin was consistently twice as fast versus the node wallet.
How Pippin Works
Pippin provides an API that mimics the Nano Wallet RPC Protocol
Every wallet-related RPC gets intercepted by Pippin and handled internally. It builds the blocks and signs them using locally-stored keys, it uses a node to publish the blocks.
Every non-wallet related RPC gets proxied to the publishing node. Which means you can make all of your RPC requests directly to Pippin whether they are wallet-related or not.
API Documentation
Recommended reference is the NANO RPC documentation, Pippin's APIs are mostly identical.
You send an HTTP Post request to pippin with the desired action and parameters, example:
{
"action": "accounts_create",
"wallet": "12345",
"count": 100
}

Supported

wallet_create
account_create
accounts_create
account_list
receive
send - Use the id parameter to prevent duplicate sends!
account_representative_set
password_change - This will also set a password, if one isn't already set
password_enter
password_valid
wallet_representative_set
wallet_add - This is for adding ad-hoc private keys to a wallet
wallet_lock
wallet_locked
wallet_balances
wallet_frontiers
wallet_pending
wallet_destroy
wallet_change_seed
wallet_contains
wallet_representative
receive_all - Not in the nano API, it takes a wallet and it will receive every pending block in that wallet (respecting receive_minimum).

Differences: Pippin vs NANO Node Wallet
These are the known differences between Pippin's API and the Nano node wallet API
Different Behavior
APIs that are different between Pippin and the Nano node wallet.

account_list accepts a count parameter that defaults to 1000
Pippin has an auto_receive_on_send option that will automatically receive pending blocks when you do a send, it will only do this if balance isnt high enough to make the transaction.
account_create does not accept an index

Fuzzy Behavior
The Nano documentation isn't perfectly clear on these, but these are how Pippin behaves.

wallet_change_seed will result in the wallet no longer being locked, if it is. The wallet has to already be unlocked before you can use this RPC, though.

Missing/Not Implemented
APIs that the Nano node wallet supports but are not implemented in Pippin.

account_move
account_remove
receive_minimum - Receive minimum can be set in config.yaml
receive_minimum_set
wallet_add_watch
wallet_history
search_pending
search_pending_all
wallet_export
wallet_ledger
wallet_republish
wallet_work_get
work_get
work_set

CLI Documentation
Pippin has a CLI interface available, you can see available subcommands with:
pippin-cli --help
The primary goal of the CLI is key management. It's a more secure way to import a seed and backup your seed.
For example a typical flow of creating a new wallet with a specific seed might look like (add --encrypt to wallet_change_seed if you want to lock the wallet with a password):
% pippin-cli wallet_create
Wallet created, ID: d897b5ec-1897-4e7e-8a90-4526f454c8de
First account: nano_31a7wzm4rayik1hthahzkekntsqz86u6dko5adg8jxueehzt5yhmhsqsuzdy
% pippin-cli wallet_change_seed --wallet d897b5ec-1897-4e7e-8a90-4526f454c8de
Enter new wallet seed: <hidden_input>
Seed changed for wallet d897b5ec-1897-4e7e-8a90-4526f454c8de
First account: nano_3ejy6ha1iuqhi5cshhifu57p5othdcymfbzsmxhjucdks53eh41yd4qpjtxf

To backup a seed (warning: this prints seed to stdout)
% pippin-cli wallet_view_seed --wallet <id>

Setting up Pippin
Requirements

Python 3.6 or newer
GCC, for MacOS and Linux
A Redis server

MacOS Instructions


Install homebrew, if it isn't already installed


Install Redis (skip if you already have done so)


% brew install gcc@9 python redis
% launchctl load ~/Library/LaunchAgents/homebrew.mxcl.redis.plist

To start redis at boot (optional):
% ln -sfv /usr/local/opt/redis/*.plist ~/Library/LaunchAgents

You may find it convenient to priorize homebrew binaries by including the install location first in your PATH.
% export PATH=/usr/local/bin:$PATH

To make it permanent:
# Catalina
% echo "export PATH=/usr/local/bin:$PATH" >> ~/.zprofile
# Others
% echo "export PATH=/usr/local/bin:$PATH" >> ~/.profile

Ubuntu 18.04
Instructions for other debian-based Linux distributions should be similar.
% sudo apt install build-essential python3.6 python3.6-dev python3-pip redis-server

CentOS 8
Install the required developer tools:
# dnf install gcc redis python3-devel

The above may require the EPEL and PowerTools repos to be configured first:
# dnf install -y install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
# dnf config-manager --set-enabled PowerTools

Redis basics for CentOS 8
After installing Redis, create directories for the Redis config and runtime files:
# mkdir /etc/redis /var/redis /var/redis/6379

By default, the dnf install places Redis config files in /etc, move them to your dedicated folders:
# mv /etc/redis-sentinel.conf /etc/redis/
# mv /etc/redis.conf /etc/redis/6379.conf

Update your Redis config file to allow it to run in the background as a daemon, supervised by systemd:
# vim /etc/redis/6379.conf
Set daemonize to yes (by default it is set to no).
Set the pidfile to /var/run/redis_6379.pid (modify the port if needed).
Change the port if necessary (6379 is the default).
Set the logfile to /var/log/redis_6379.log
Set the working dir to /var/redis/6379
supervised systemd

Create the Systemd service to have Redis start automatically:
# vim /etc/systemd/system/redis.service
[Unit]
Description=Redis
After=syslog.target

[Service]
Type=notify
PIDFile=/var/run/redis_6379.pid
ExecStart=/usr/bin/redis-server /etc/redis/6379.conf --supervised systemd
Restart=on-failure

[Install]
WantedBy=multi-user.target

Enable and start the service:
# systemctl enable --now /etc/systemd/system/redis.service

Verify that Redis is running:
# systemctl status redis
# redis-cli ping

Installing Pippin
First, update PIP to latest version.
% pip3 install -U pip

For MacOS you might need to set the following environment variable:
export CC=/usr/local/bin/gcc-9

To install Pippin on macos or Linux
% pip install --user pippin-wallet

Windows requires visual c++ and should be prefixed with USE_VC=1
% USE_VC=1 pip install pippin-wallet

To upgrade Pippin in the future, add --upgrade
% pip install --upgrade pippin-wallet

Configuring Pippin
Pippin creates a PippinData directory in your home directory.
Run: pippin-server --generate-config to generate a sample in ~/PippinData/sample.config.yaml
Using BoomPoW
Want to use BPoW?
Pippin will use them automatically for work generation if the key is present in the environment.
For BPoW:
% echo "BPOW_KEY=service:mybpowkey" >> ~/PippinData/.env

Configuring PostgreSQL or MySQL
Pippin uses SQLite by default, which requires no extra configuration.
To use postgres or mysql, you need to put your database information in some environment variables
Postgres:
Required (replace database_name, user_name, and mypassword with the actual values):
% echo "POSTGRES_DB=database_name" >> ~/PippinData/.env
% echo "POSTGRES_USER=user_name" >> ~/PippinData/.env
% echo "POSTGRES_PASSWORD=mypassword" >> ~/PippinData/.env

Optional:
# 127.0.0.1 is default
% echo "POSTGRES_HOST=127.0.0.1" >> ~/PippinData/.env
# 5432 is default
% echo "POSTGRES_PORT=5432" >> ~/PippinData/.env

MySQL:
Required (replace database_name, user_name, and mypassword with the actual values):
% echo "MYSQL_DB=database_name" >> ~/PippinData/.env
% echo "MYSQL_USER=user_name" >> ~/PippinData/.env
% echo "MYSQL_PASSWORD=mypassword" >> ~/PippinData/.env

Optional:
# 127.0.0.1 is default
% echo "MYSQL_HOST=127.0.0.1" >> ~/PippinData/.env
# 3306 is default
% echo "MYSQL_PORT=3306" >> ~/PippinData/.env

Changing Redis Host/Port
Pippin uses Redis for distributed locks, so that every account works on its own chain in a synchronous fashion.
By default, it will look for redis on 127.0.0.1 on port 6379 and use db 0, you can also change these with environment variables.
echo "REDIS_HOST=127.0.0.1" >> ~/PippinData/.env
echo "REDIS_PORT=6379" >> ~/PippinData/.env
echo "REDIS_DB=0" >> ~/PippinData/.env
echo "REDIS_PW=supersecretpassword" >> ~/PippinData/.env

Pippin Configuration
Pippin uses a yaml based configuration for everything else.
All available options are in a sample file.
You can override any default by creating a file called ~/PippinData/config.yaml and choosing your own settings.
It must be in your users home directory in a folder called PippinData
Configuring Pippin for BANANO
In config.yaml set banano: true
# Settings for the pippin wallet
wallet:
# Run in banano mode
# If true, the wallet will operate based on the BANANO protocol
# Default: false
banano: true

Configuring the node
At the bare minimum, Pippin requires a node for the RPC api. It will default to http://[::1]:7076 for Nano, or http://[::1]:7072 for BANANO. If you want to change it to https://coolnanonode.com/rpc then it would look like this:
server:
# The RPC URL of the remote node to connect to
# Non-wallet RPCs will be routed to this node
# Default: http://[::1]:7076 for nano, https://[::1]:7072 for banano
node_rpc_url: https://coolnanonode.com/rpc

Running Pippin
Once configured, just start it with pippin-server
It can be started on boot using systemd (Linux)
Create a file /etc/systemd/system/pippin.service
With the contents:
[Unit]
Description=Pippin Wallet
After=network.target

[Service]
Type=simple
User=YOUR_LINUX_USER
Group=YOUR_LINUX_USER
ExecStart=/home/myuser/.local/bin/pippin-server

[Install]
WantedBy=multi-user.target

If you aren't sure what the full path of pippin-server is, run which pippin-server
Then enable and start
% sudo systemctl enable pippin
% sudo systemctl start pippin

Endpoints
Send HTTP POST requests to Pippin just like you would a normal node.
% curl -g -d '{"action":"wallet_create"}' localhost:11338
% curl -g -d '{"action":"account_balance", "account": "nano_3jb1fp4diu79wggp7e171jdpxp95auji4moste6gmc55pptwerfjqu48okse"}' localhost:11338

Auto-receive & Dynamic PoW
To automatically pocket pending transactions as they arrive, callback is required.
Hooking up the websocket also adds support for dynamic PoW which means that blocks will get confirmed faster if the active difficulty is higher than the minimum.
Pippin only supports the websocket callback, which can be setup like so in config.yaml:
server:
# The WebSocket URL of the node to connect to
# Optional, but required to receive transactions as they arrive to accounts
# Default: None
#node_ws_url: ws://[::1]:7078

Feature requests
Notice an API that's missing a feature or not behaving the same as nano's APIs?
Open a bug report/feature request on the issues page