WhoSoup commented 3 years ago

Changelog for 0.4.0 (the "go.mod release")

As the name already implies, the big change is that this version finally moves away from glide and introduces go.mod. This release also contains some breaking changes for retrieving blocks and transactions.

No raw data

The factomd API methods for block retrieval typically return both a json representation as well as the raw factom marshalled bytes of the block. There are very few applications where you need both the unmarshalled block and the raw bytes at the same time. You either need the unmarshalled data only, or if you need the raw bytes, you can unmarshal it locally. Transmitting both at the same time wastes bandwidth if only one is used.

The new factomd version (6.9.0-Wax) adds a new parameter to these API methods ("noraw") that allows us to retrieve the unmarshalled data without the raw. To get the raw data only, we can use the separate "get-raw" endpoint. The client now reflects this and the common block retrieval methods no longer return the raw data:

GetABlock(string) (*ABlock, []byte, error) => GetABlock(string) (*ABlock, error)
GetABlockByHeight(int64) (*ABlock, []byte, error) => GetABlockByHeight(int64) (*ABlock, error)
GetDBlock(string) (*DBlock, []byte, error) => GetDBlock(string) (*DBlock, error)
GetDBlockByHeight(int64) (*DBlock, []byte, error) => GetDBlockByHeight(int64) (*DBlock, error)
GetECBlock(string) (*ECBlock, []byte, error) => GetECBlock(string) (*ECBlock, error)
GetECBlockByHeight(int64) (*ECBlock, []byte, error) => GetECBlockByHeight(int64) (*ECBlock, error)
GetFBlock(string) (*FBlock, []byte, error) => GetFBlock(string) (*FBlock, error)
GetFBlockByHeight(int64) (*FBlock, []byte, error) => GetFBlockByHeight(int64) (*FBlock, error)

To retrieve the raw data for these blocks, use:

GetRaw(keymr string) ([]byte, error)
GetBlockByHeightRaw(string, int64) (*BlockByHeightRawResponse, error)

Anchors

The client now supports the "anchors" API endpoint via the following two functions:

GetAnchors(hash string) (*Anchors, error)
GetAnchorsByHeight(height int64) (*Anchors, error)

The Anchors struct contains the height, keymr, as well as a potential Bitcoin or Ethereum anchor. Not all blocks have anchors and they are nil if missing: https://github.com/FactomProject/factom/blob/afafc3a8957f254a59a7b199552b2f1e87cd78a1/anchors.go#L12-L37

Pending Entries / Transactions

Instead of returning the raw json response as a string, the client now unmarshals the pending entries and transactions:

GetPendingEntries() (string, error) => GetPendingEntries() ([]PendingEntry, error)
GetPendingTransactions() (string, error) => GetPendingTransactions() ([]PendingTransaction, error) The PendingEntry struct contains the chainid, entry hash, and status. The PendingTransaction contains txid, dbheight, status, fees, inputs, and outputs

FBlock Transactions

The FBlock structure now contains the unmarshalled list of transactions rather than the raw json response. FBlock.Transactions is of type "FBTransaction" which contains the txid, height, timestamp, signed input transactions, and the fct/ec outputs: https://github.com/FactomProject/factom/blob/afafc3a8957f254a59a7b199552b2f1e87cd78a1/fblock.go#L29-L57

Open Node Support

The open node is a cluster of nodes that sit behind a load balancer. Sometimes this can cause issues with slightly inconsistent data between calls. The open node has enabled cookie sessions which ensure that all requests in the same session target the same node. There are two ways you can use this:

factom.SetOpenNode()

This call will set the factomd endpoint to the open node and enable the cookie jar.

factom.EnableCookies()

This enables cookies but does not change the factomd endpoint. You can also use this to reset cookies.

Other

The /wallet/ folder has been removed and will be relocated to its own repo. This was done because the contents were unrelated to the client and it bloated imports significantly.
A new function EntryCommitMessage(e *Entry, ec *ECAddress) (*bytes.Buffer, error) has been made public. It returns the raw bytes of what would be sent to factomd when using the ComposeEntryCommit function, allowing you to build commits without sending them.
The automated circle tests have been improved

PaulBernier commented 3 years ago

Thank you for putting that together! I think we can move forward with releasing v0.4 as soon as the wallet utilities that has been removed are available https://github.com/FactomProject/wallet (otherwise it could prevent some users to upgrade as they would lost features).