Extending the Markdown spec to reference contract storage resources

Research and Development
1

Hello,

We are currently working on a solution to write articles about tezos blockchain content, and thought it would be cool to create a markdown specification to reference tezos smart contract resources within the articles. The end goal is to provide a shared syntax so that any dapp could share these rich articles with content enhanced by blockchain data. The most basic example would be the inclusion of a NFT in the body of the article without the need to manually include an image, link and text to reference the NFT.

We propose the following syntax:


{key:value;key:value}(optional description)
  • A line, separated by 2 empty lines from the rest of the content, one above and one below.
  • A list of key:value pairs separated by semicolons, surrounded by brackets.
  • Optionally, a text description surrounded by parenthesis directly following the closing bracket.

List of the keys and their values:

  • type (default: TZIP-012): the type of the ressource. By default points to the FA2 spec, but it can be used to provide some insights on the data being represented.
  • metadata_spec (default: TZIP-021): the specification of the metadata being fetched. This will help the module responsible for displaying the media block. For instance, fxhash projects are not NFTs and their metadata shouldn’t be displayed like other NFTs. A different SPEC would be used there.
  • address (required): the contract address in which the resource can be found
  • bigmap (default: token_metadata): the bigmap annotation in which the data is stored
  • key (required): the bigmap key under which the token metadata can be fetched
  • value (default: ‘token_info’.’’): an object-style path defining how the json metadata can be extracted from the bigmap value. If empty, the value of the bigmap will directly be used

This specification should allow for any contract-storage resource to be represented, with some room for custom resources as well.

The most basic use-case would be the representation of an FA2 asset, for instance OBJKT#741172 from hicetnunc objkt contract:


{address:KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton;key:741172}

Is this specification missing anything to represent any contract storage data (should we provide something else than bigmaps for instance) ?

Would this markdown specification work ? Does it collide with anything already existing ? Should we provide a clearer identifier to clearly mark it as “tezos blockchain contract storage asset” ?

Also, and more generally, do we have a generic specification that defines “how to represent any data within a contract storage” ?

3 Likes
2

We’ve been reworking the proposal to align it on an already established markdown directive specification. I don’t think this is an official spec but it’s supported by many markdown processor plugins and as such its integration would be easier.

The spec is described in the following documents:

It would look like this:

::tezos-storage[optional descriptive text]{address="KT1RJ6PbjHpwc3M5rw5s2Nbmefwbuwbdxton" key="741172"}
  • :: because this a leaf node type
  • tezos-storage as the identifier of the block type
  • [] to optionally add contextual string to the block
  • {key="value" key2="value} as a list of key-pair values, reusing the same keys as the ones described in the original proposal.
1 Like