Nano Bench Proposal

Problem statement:

Nano does not have a standardized way to transfer/store off chain accounting data.

Short description:

Nano Bench is an open source wallet SDK. Data can either be put on or taken off the 'bench', which is a side chain superset of a nano account chain stored locally by client.

Architecture diagram:


  • The SDK is the main handler for user input with a focus on Nano URIs
  • It is also responsible for block/hash handoff protocol
  • Consumes Nano URIs with custom parameters and provides wallet with initial block details
  • Accepts confirmed block details from wallet and stores locally
  • Allows 'bench' data to be imported and exported to other wallets and software

Nano URIs:

The SDK will have special methods to handle parameters regarding block handoffs.

Ex 1: nano:nano_{account}?amount=1&handoff_type={hash/block}&handoff_url={merch api endpoint}

The SDK will wait for wallet to provide hash or signed block and then deliver to {merch api endpoint}

Custom params:
Ex: 2: nano:nano_{account}?amount=1&fiat=usd&fiat_value=1000&memo='nano to moon'

All custom parameters will be parsed and saved to the 'bench' for the corresponding block.


  • Standardizes the handling of user input across wallet providers
  • A modular / central place for future wallet updates that works in tandem with protocol updates.
  • Can be expanded to provide helper methods for signing and mnemonic phrases
  • Less code for wallet providers
  • Solves payment id handoff
  • Provides flexible way to store other relevant accounting data for taxes etc.

Further recommendations:

While this SDK could be run by anyone, it should be operated by NF as they have the most influence and leadership over wallet providers. It would also be a nice addition to the linux-like platform they plan to become.

The SDK should be written in either C++ or Dart for portability and bindings to other languages and platforms.

The 'bench' can use any data structure for local storage however I would recommend a structure with double entry accounting as that is a finance standard. Here is a rough JSON layout:

    "000D1BAEC8EC208142C99059B393051BAC8380F9B5A2E6B2489A277D81789F3F": { /* Wallet ID */
        "accounts": { /* account dictionary */ 
            "nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z": {
                "balance": "999", /* current running balance */
                "credits": { /* all transactions going out of account with send block */ 
                    "E2FB233EF4554077A7BF1AA85851D5BF0B36965D2B0FB504B2BC778AB89917D3": { /* Key: confirmed block hash, Val: extended block details dict */
                        "subtype": "send",
                        "to": "nano_33t5by1653nt196hfwm5q3wq7oxtaix97r7bhox5zn8eratrzoqsny49ftsd",
                        "amount": "1", /* nano amount */
                        "fiat": "usd",
                        "fiat_value": "1000",
                        "memo": "rent corp 7285",
                        "handoff_type": "hash", /* either 'hash' or 'block' */
                        "handoff_url": "",
                        "local_timestamp": "1636398402",
                        "confirmed_block": {
                            "type": "state",
                            "account": "nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z",
                            "previous": "6CDDA48608C7843A0AC1122BDD46D9E20E21190986B19EAC23E7F33F2E6A6766",
                            "representative": "nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh",
                            "balance": "1000000000000000000000000000000",
                            "link": "87434F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358FD6F9",
                            "link_as_account": "nano_33t5by1653nt196hfwm5q3wq7oxtaix97r7bhox5zn8eratrzoqsny49ftsd",
                            "signature": "A5DB164F6B81648F914E49CAB533900C389FAAD64FBB24F6902F9261312B29F730D07E9BCCD21D918301419B4E05B181637CF8419ED4DCBF8EF2539EB2467F07",
                            "work": "000bc55b014e807d"
                "debits": { /* all transactions coming into account with recieve block */ 
                    "DBO3233EF4554077A7BF1AA85851D5BF0B36965D2B0FB504B2BC778AB899A43Z": { 
                        "subtype": "recieve",
                        "from": "nano_46sAblk1653nt196hfwm5q3wq7oxtaix97r7n8eratrzoqsnygenerousStranger",
                        "amount": "100",
                        "fiat": "usd",
                        "fiat_value": "100000",
                        "memo": "a generous gift",
                        "local_timestamp": "1636398402",
                        "confirmed_block": {
                            "type": "state",
                            "account": "nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z",
                            "previous": "932BA48608C7843A0AC1122BDD46D9E20E21190986B19EAC23E7F33F2E6AE897",
                            "representative": "nano_3pczxuorp48td8645bs3m6c3xotxd3idskrenmi65rbrga5zmkemzhwkaznh",
                            "balance": "100000000000000000000000000000000",
                            "link": "99BeF4F8041869A01C8F6F263B87972D7BA443A72E0A97D7A3FD0CCC2358F9TO1",
                            "link_as_account": "nano_46sAblk1653nt196hfwm5q3wq7oxtaix97r7n8eratrzoqsnygenerousStranger",
                            "signature": "A5DB164F6B81648F914E49CAB533900C389FAAD64FBB24F6902F9261312B29F730D07E9BCCD21D918301419B4E05B181637CF8419ED4DCBF8EF2539EB2467F07",
                            "work": "000bc55b014e807d"

Also to clarify, the kit would consume raw user input as well which could be anything. A basic nano address or any new future format like nano_{address}_{suffix block field or data}. Maybe even a hashed Nano URI for easier copy /paste.

1 Like

Tagging @koczadly here for visibility as they were looking into some of this stuff recently.

1 Like

Thanks for the suggestion! Just to be clear, I take the goal here is to have a standardized set of software libraries to reduce the complexity with integrating Nano into wallets? I had considered creating a dart library for the handoff protocol we're developing given the complexity of it; this could just be an extension of that, though more general to Nano's other features.

I absolutely do think the complexity of wallet integrations needs to be reduced though, and some kind of wallet-oriented library/SDK would be a great help here. Research into integrating Nano with Podcasting 2.0 has shown that supporting apps would need to implement their own built-in wallet to manage user funds, which is not only somewhat difficult but requires a lot of thought into security and storage of private keys — a simple API for storing seeds, sending and receiving funds and changing the account rep would probably be ideal here, abstracting away all the inner complexities and protocols. I'll definitely look into this more over the next few weeks and see what current solutions are already available.

Something I'm not entirely sold on is the need for local storage, though I can appreciate there's a couple smaller use cases (related topic). What would be the primary use-case of this functionality? I'd imagine most wallets (especially multi-crypto ones) would choose to use their own database system and serialization format depending on what they require, and most wallets currently appear to simply retrieve the data remotely when requested, either from a remote database or the ledger/blockchain. Obviously this isn't so useful for off-chain data however, but I'm not sure what use-cases their would be for that — if you could fill me in on a few ideas here that'd be much appreciated.

Yea the main goal is a unified wallet SDK/library that acts as a 'swiss-army knife' for different integration problems.

Payment ids:
Although I think on chain solutions would be simpler, an off chain hash handoff is the next best imo. But implementing that solution comes with large 'human tax' to get it done. I think a wallet SDK/library would be the easiest approach, and if it comes with other code benefits and convenience it would further incentivize its use.

Accounting meta data:
Fiat amounts, exchange rates, and extended memos are important for every transaction for taxes and accounting. We have talked in other threads about this. Although its not a huge requirement now, I think these features will become more important in the future. The 'bench' storage idea is a flexible, optional, way to plan for that future. Also if ledger pruning gets implemented, it provides a nice backup method for full account transaction history. Regarding where to store the bench data, the SDK could have methods for local or remote storage via webhook post for each tx. Imagine a future where governments could store 'bench' data for a Nano account you have setup with your employer. Income taxes could be fully automated. My main point though is we don't know yet how it will be used and there is no harm to designing an optional, flexible off chain protocol for it.

SDK convenience methods:
It would be great to have an 'approved' set of libraries for generating seeds, mnemonic phrases, signing blocks etc and everything else that is wallet agnostic.

Nano URIs
This is the UX for how all this info gets passed around. The two examples above highlight the use for payment id and meta data transfer.

Logging another example here from reddit:

Say I am a local coffee shop and you want to buy a drink with Nano. I give you a QR code with this Nano URI embedded:

nano:nano_1qato4k7z3spc8gq1zyd8xeqfbzsoxwo36a45ozbrxcatut7up8ohyardu1z? amount =1& handoff_type =hash& handoff_url fiat =USD& fiat_value =3.73& memo =medium coffee brew from BigBrew INC

Fait, fiat_value, and memo data will all be stored locally in your wallet with the confirmed sent block. The data is stored in a standardized way (Nano Bench) so it can be exported and imported to other wallets and tax/accounting software.

Also notice for me as a merchant its super easy to validate the payment succeeded, and came from your session id /123 since I get the confirmed block hash (fully automated as well).

To help with tax software... for cryptocurrencies...
I'm going to eat a shoe.

Ya screw taxes, traditional accounting, the law and government. We can phase them all out at once am I right?

The switch to cryptocurrencies is the perfect phasing opportunity.

Join the (r)evolution.

Well I will respect that as your opinion. Lets keep any future posts on topic for this thread.

I'm looking forward to a standard that helps compatibility between wallet products

After a bit more thought, a better architecture would be to fully isolate all the wallet code and separate it from the UI entirely.

If enough wallet providers use this setup, it would be very easy to maintain and enhance L2 handoff protocols from a central (open source) place moving forward.

1 Like