Skip to main content

AncillaryData

AncillaryData#

We assume that on-chain ancillary data can be formatted directly from bytes to utf8 encoding via web3.utils.hexToUtf8, and that clients will parse the utf8-encoded ancillary data as a comma-delimitted key-value dictionary. Therefore, this library provides internal methods that aid appending to ancillary data from Solidity smart contracts. More details on UMA's ancillary data guidelines below: https://docs.google.com/document/d/1zhKKjgY1BupBGPPrY_WOJvui0B6DMcd-xDR8-9-SPDw/edit

Functions#

toUtf8Bytes(bytes32 bytesIn) → bytes (internal)

Returns utf8-encoded bytes32 string that can be read via web3.utils.hexToUtf8.

Will return bytes32 in all lower case hex characters and without the leading 0x. This has minor changes from the toUtf8BytesAddress to control for the size of the input.

Parameters:#

  • bytesIn: bytes32 to encode.
toUtf8BytesAddress(address x) → bytes (internal)

Returns utf8-encoded address that can be read via web3.utils.hexToUtf8. Source: https://ethereum.stackexchange.com/questions/8346/convert-address-to-string/8447#8447

Will return address in all lower case characters and without the leading 0x.

Parameters:#

  • x: address to encode.
toUtf8BytesUint(uint256 x) → bytes (internal)

Converts a uint into a base-10, UTF-8 representation stored in a string type.

This method is based off of this code: https://stackoverflow.com/a/65707309.

appendKeyValueBytes32(bytes currentAncillaryData, bytes key, bytes32 value) → bytes (internal)
appendKeyValueAddress(bytes currentAncillaryData, bytes key, address value) → bytes (internal)

Adds "key:value" to currentAncillaryData where value is an address that first needs to be converted to utf8 bytes. For example, if utf8(currentAncillaryData)="k1:v1", then this function will return utf8(k1:v1,key:value), and if currentAncillaryData is blank, then this will return utf8(key:value).

Parameters:#

  • currentAncillaryData: This bytes data should ideally be able to be utf8-decoded, but its OK if not.
  • key: Again, this bytes data should ideally be able to be utf8-decoded, but its OK if not.
  • value: An address to set as the value in the key:value pair to append to currentAncillaryData.
appendKeyValueUint(bytes currentAncillaryData, bytes key, uint256 value) → bytes (internal)

Adds "key:value" to currentAncillaryData where value is a uint that first needs to be converted to utf8 bytes. For example, if utf8(currentAncillaryData)="k1:v1", then this function will return utf8(k1:v1,key:value), and if currentAncillaryData is blank, then this will return utf8(key:value).

Parameters:#

  • currentAncillaryData: This bytes data should ideally be able to be utf8-decoded, but its OK if not.
  • key: Again, this bytes data should ideally be able to be utf8-decoded, but its OK if not.
  • value: A uint to set as the value in the key:value pair to append to currentAncillaryData.
constructPrefix(bytes currentAncillaryData, bytes key) → bytes (internal)

Helper method that returns the left hand side of a "key:value" pair plus the colon ":" and a leading comma "," if the currentAncillaryData is not empty. The return value is intended to be prepended as a prefix to some utf8 value that is ultimately added to a comma-delimited, key-value dictionary.