Skip to content

Latest commit

 

History

History
192 lines (152 loc) · 5.74 KB

wip-0021.md

File metadata and controls

192 lines (152 loc) · 5.74 KB
  WIP: WIP-0021
  Layer: Consensus (hard fork)
  Title: Add StringParseXMLMap to RADON operators
  Authors: Luis Rubio 
  Discussions-To: `#dev-general` channel on Witnet Community's Discord server
  Status: Final
  Type: Standards Track
  Created: 2021-12-14
  License: BSD-2-Clause

Abstract

The StringParseXMLMap operator is proposed to be included in the operators catalog available in the RAD engine. Data requests will then support XML parsing as part of the retrieval scripts.

Motivation and rationale

In order to increase the flexibility and potential use cases of the Witnet protocol, it is paramount to continue expanding the catalog of available operators.

This document proposes adding support for XML parsing, thus allowing the protocol to extract information from XML APIs or XML-encapsulated strings to be retrieved through data requests.

Specification

The StringParseXMLMap operator converts a String (which is assumed to represent a valid XML document) into a Map, following the next rules:

  • The XML document itself MUST be turned into a Map in which the root element will act as its only entry, using its tag name as the key:
    <rootElement>
    </rootElement>
{
    rootElement: "",
}
  • Every element MUST be turned into a Map and inserted as an entry into the Map of its parent element using its tag name as the key. Attributes MUST be inserted as entries into those Maps with their name preceded by the @ symbol. Namespace attributes MUST be treated the same as any other attribute.
<tag1 attr1="001">
    <in_tag1>Hello</in_tag1>
    <in_tag2>World</in_tag2>
</tag1>
{
    tag1: {
        @attr1: "001",
        in_tag1: "Hello",
        in_tag2: "World",
    }
}
  • Leaf elements that have no attributes or children other than textual content MUST be added as an entry in the Map of their parent element using their tag as the keys and their textual content as the values.
<tag1 attr1="001">
    <in_tag1>Hello</in_tag1>
    <in_tag2><Name>Witnet</Name></in_tag2>
</tag1>
{
    tag1: {
        @attr1: "001",
        in_tag1: "Hello",
        in_tag2: {
            Name: "Witnet",
        },
    }
}
  • Elements with the same tag name MUST be collected into a RadonArray with the tag name in common as a key of the parent Map.
<tag1 attr1="001">
    <in_tag>Hello</in_tag>
    <in_tag>
      <Name>Witnet</Name>
    </in_tag>
</tag1>
{
    tag1: {
        @attr1: "001",
        in_tag: [
            "Hello",
            {
                Name: "Witnet",
            },
        ],
    }
}
  • Text children elements MUST be included into the parent Map using the _text key.
<tag1 attr1="001">
    <in_tag1>
        Hello
        <in_in_tag1>World</in_in_tag1>
        Witnet
    </in_tag1>
    <in_tag2 attr="hello">World</in_tag2>
    <in_tag3>HelloWorld</in_tag3>
</tag1>
{
    tag1: {
        @attr1: "001",
        in_tag1: {
            _text: [
                "Hello",
                "Witnet"
            ],
            in_in_tag1: "World",
        },
        in_tag2: {
            @attr: "hello",
            _text: "World",
        },
        in_tag3: "HelloWorld",
    }
}

Backwards compatibility

  • Implementer: a client that implements or adopts the protocol improvements proposed in this document.
  • Non-implementer: a client that fails to or refuses to implement the protocol improvements proposed in this document.

Consensus cheat sheet

Upon entry into force of the proposed improvements:

  • Blocks and transactions considered valid by former versions of the protocol MUST continue to be considered valid.
  • Blocks and transactions produced by non-implementers MUST be validated by implementers using the same rules as with those coming from implementers, that is, the new rules.
  • Implementers MUST apply the proposed logic when evaluating transactions or computing their own data request eligibility.

As a result:

  • Non-implementers MAY NOT get their blocks and transactions accepted by implementers.
  • Implementers MAY NOT get their valid blocks accepted by non-implementers.
  • Non-implementers MAY consolidate different blocks and superblocks than implementers.

Due to this last point, this MUST be considered a consensus-critical protocol improvement. An adoption plan MUST be proposed, setting an activation date that gives miners enough time in advance to upgrade their existing clients.

Libraries, clients, and interfaces

The protocol improvements proposed herein will affect any library or client implementing any functionality related to the RAD engine. For example, this is the case of the Sheikah data request editor and the witnet-requests-js Javascript library.

Reference Implementation

A reference implementation for the proposed protocol improvement can be found in the pull request #2138 of the witnet-rust repository.

Adoption Plan

An activation date is proposed for April 5 2022 at 9am UTC, that is, protocol epoch #1032960.

From the perspective of TAPI, the signaling bit is 2 (0b00000000000000000000000000000100) and the first_signaling_epoch is set to #1032960.

Acknowledgements

This proposal has been cooperatively discussed and devised by many individuals from the Witnet development community.

Special thanks to Witnet devs for contributing to the reference implementation in Rust.