We’re close to rolling out version 4.0.0 of the Hiro’s Stacks Blockchain API.
One of the most important upgrades we’re shipping with this release is the use of Matt Little’s new Node.js native addon library, which encodes and decodes binary wire formats for the Stacks blockchain and brings huge CPU performance improvements to our deployments. This library follows the Clarity language reference to the letter.
For most API users, this change is completely transparent. However, if your Stacks app depends on reading Clarity repr values directly for contract calls, function arguments, etc., you’ll notice a difference in how the new library returns Clarity principal strings (STX addresses and smart contract IDs).
In previous versions (≤ 3.0.3), our API incorrectly returned these strings without a ' (single quote) prefix, but the Clarity reference clearly specifies principals should always be returned with a leading single quote.
This is how an example Clarity value will be returned starting in 4.0.0:
"value": {
"hex": "0x0c0000000401610d0000000c6c6973742d696e2d757374780a636f6d6d697373696f6e06164e6fd36701abf835bd46f37c428b3dea31ad6ddf17636f6d6d697373696f6e2d62797a616e74696f6e2d7635026964010000000000000000000000000000091e057072696365010000000000000000000000001c9c3800",
"repr": "(tuple (a \"list-in-ustx\") (commission 'SP176ZMV706NZGDDX8VSQRGMB7QN33BBDVZ6BMNHD.commission-byzantion-v5) (id u2334) (price u480000000))"
}
Notice how the principal within repr is returned as 'SP176ZMV706NZGDDX8VSQRGMB7QN33BBDVZ6BMNHD.commission-byzantion-v5
As a general principle, we recommend that you always parse the Clarity value provided in hex into a structured object from which you’d then take any data you need instead of parsing the repr string directly. The API provides repr strings mostly for human readability.
If this represents a breaking change to you, please let us know so we can take your specific case into consideration before beginning the rollout. Otherwise, we plan to start serving version 4.0.0 in a week, after May, 18th, 2022.