Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
BSIP60: BitShares URI scheme #131
A Uniform Resource Identifier (URI) is a string of characters that unambiguously identifies a particular resource.
The most common form of URI is the Uniform Resource Locator (URL), frequently referred to informally as a web address.
This BSIP defines a Uniform Resource Name (URN), for the BitShares network.
Currently, BitShares lack any URL/URI scheme, forcing users to laborously copy and paste several pieces of data from/to different bitshares software.
Bitcoin (and other cryptocurrencies) generally have an URI scheme, making it possible to embed payment links into websites, emails and other forms of digital media.
Having a schema also enables support to generate and read QR codes. QR codes are of great convenience to the users, and is a defacto method of transfering URLs between desktop and mobile applications.
Even a mere existance of this BSIP could greatly raise interoperability between different BitShares software implementations.
Some clients have gone ahead and implemented their own incompatible schemas, which were never agreed on. This is not healthy for the ecosystem.
The URI schema outlined in this BSIP is aimed to provide flexibility and future extensibility, while adhering to general Internet standarts.
The most requested form of an URI (representing a potential transfer) is defined here, along with a more generic, all-base-covering approach.
The BitShares URI conforms to general URI structure, outlined in RFC1738.
Each URI points to an "noun", an object of some kind, and does not represent action (or "verb"). However, since BitShares Operation is an object, this scheme can express operations.
The protocol name is
All paths follow the
Note, that as BitShares blockchain evolves, some of the addressing schemes might get expanded, in which case the bitshares-core consensus always supersedes the rules specified in this BSIP.
Parameters are URL-encoded. Parameters are key/value pairs separated by "=" symbol, delimited by "&".
Extended syntax for nesting deep objects is also allowed, so those are valid:
See Operation path definition for examples and rationale.
Raw Object paths start with "object", followed by a
Asset paths start with the string "asset", followed by an
Account paths start with the string "account", followed by an
Market paths start with the word "market", followed by two
Public Key paths start with the "public_key" word, followed by
Client guideline: add key as a blind contact with label provided.
Operation paths start with the word "operation", followed by
Client guideline: open an interface to perform described operation, pre-populate input fields with parameters provided.
Here, parameter names MUST match the operation parameters. For example, classic Transfer operation has the following fields in the BitShares specification:
Deep objects MAY be represented via extended URL parameter syntax, for example, in BitShares, amounts are usually encoded as:
This MAY be represented as
Wallet software SHOULD respect such notation, making the process of adding new operations to the scheme seamless.
However, for simplicity sake, a shortening method SHOULD be implemented. Continuing with the amount example, a transfer operation MAY paramterize as
A conversion table is provided below:
Each operation MAY also have an optional
Operation names are defined here:
Blind Receipt paths start with the word "blind_receipt", followed by
Block / TRX / Operation path
Block / TRX / Operation paths all start with the word "block", but can point to either a whole block, either a transaction in that block, either an op within that transaction (with virtual op to help navigate).
Client guideline: show block explorer, highlight operation.
Transaction by hash
A note on client guidelines
BitShares clients MUST NOT act on URIs without getting the user's authorization. They SHOULD require the user to manually approve each operation individually, though in some cases they MAY allow the user to automatically make this decision.
Operating system integration
Graphical BitShares clients SHOULD register themselves as the handler for the "bitshares:" URI scheme by default, if no other handler is already registered. If there is already a registered handler, they MAY prompt the user to change it once when they first run the client.
A shortening scheme was proposed, during the discussion, which allows to replace each
In addition, instead of spelling out operation type (e.g. "transfer"), it's id number could be used (so the
Summary for Shareholders
Adding an agreed-on standard for the URI schema will allow different BitShares software to interoperate and share data on user interface level.
This BSIP is placed in the public domain.
Prior work, bitshares1 XTS URLs:
referenced this issue
Dec 12, 2018
This BSIP tries to unify several different ideas, and as such I personally don't agree with everything on it.
In particular, the
Given that we call it "BitShares" today, I am not sure it makes any sense adding it to the URI scheme.
Other than that, I like this proposal! +5%
Thanks for the reviews!
I've updated the text with the following:
Looking forward for more comments and suggestions.
Also, I think, that if we do agree, on the "shortening scheme" ("operation/transfer"->"op/0", from the "Discussion" section) it should be moved to the text proper, and if we don't, a word or two about the rationale should be added (e.g. "it can win us some bytes, but in the end, not worth it"). Please tell me what you think, and I'll do either this or that.
@pmconrad, thanks a lot for your review. I'm especially grateful that you took time to review the BNF.
ATOMIC_INTEGER is normal integer (which is, as you said, indivisible too), I was just trying to drive the point home -- that it is NOT a float, and that we're talking about "satoshi" amounts of tokens. I also believe that's what those values are (informally) called in bitshares-core code, and in some other cryptocurrencies. I'll think about rewording this somehow.
Edit: OK, text updated. Note, that I'm using same BNF syntax as in RFC1738, so I'm writing
Thanks. Yes, that clarifies it.
Some more things:
I'm unsure if it would be better to allow both upper- and lowercase letters in the URL and specify that they must be converted to the appropriate case by the client.
@pmconrad, you have a keen eye :) Thanks.
I've managed to include most of those rules, but some things like size constraints (especially maximum length) are hard to express with BNF. I've also added a note explaining that bitshares-core is the authoritative source for those rules and not this spec (e.g. "ASSET.SUBASSET" did not always exist, and I imagine more mutations might appear in the future).
I don't think we should get too overboard with constraining the URLs, and we probably should actually allow any kind of garbage in there, to be dealt with other layers of the software (e.g. "account/12improper___NAME" could just yield "no such account" error on a higher level). Just a thought, though; like I said, I've updated the text, implementing most of your remarks.
It is, as far as I know.
Original discussion and references are here
Is that format something that is already well-known/established for other blockchains (bitcoin)? If so, I think we should adopt it. Thoughts?
Hm. I don't see why
As in Vote for bitshares:cyrano now!!!. Or Feed producers needed for bitshares:HERTZ.
Yes, it is. Bitcoin, all bitcoin-derived coins, and other "simple" coins all use this notation. By "simple", I mean coins that only support one type of operation -- a transfer. In such coins, no ambiguity is present at all.
Personally, I agree with abitmore in regards to the original discussion: bitshares is not a "simple" blockchain, we have 40+ operations, and I think it helps to be as explicit as possible. In short: no, I don't think we should adopt it.
This sounds very dangerous, 1 case conversion function on either end can cripple the meaning beyond recovery (there are certainly accounts and assets with the same name, I'm thinking gateway accounts and gateway base coins).
I understand the wish to be similar to other coins, and also for an easy-to-write-by-hand URLs, but I also think it's just not worth it, given the dangers.
(Yet again: I'm just a humble servant, and will readily adopt the spec to your liking, but I believe abitmore made very good points, and I wrote this BSIP with them in mind).