def entries_at_height(
self,
chain_id: Union[bytes, str],
height: int,
include_entry_context: bool = False,
encode_as_hex: bool = False
):
"""
A generator that yields all entries in a chain that occurred at the
given height.
"""
# Look for the chain id in the directory block entries
target_chain_id = utils.hex_from_bytes_or_string(chain_id)
directory_block = self.directory_block_by_height(height)["dblock"]
for entry_block_pointer in directory_block["dbentries"]:
if entry_block_pointer["chainid"] == target_chain_id:
entry_block_keymr = entry_block_pointer["keymr"]
break
else:
return [] # Early return, chain didn't have entries in this block
# Entry block found, yield all entries within the block
entry_block = self.entry_block(entry_block_keymr)
yield from self.entries_in_entry_block(entry_block, include_entry_context,
encode_as_hex)
def transactions_by_txid(self, tx_id: Union[bytes, str]):
"""
This will retrieve a transaction by the given TxID. This call is the fastest way to retrieve a transaction,
but it will not display the height of the transaction. If a height is in the response, it will be 0.
To retrieve the height of a transaction, use the By Address method.
"""
return self._request("transactions", {"txid": utils.hex_from_bytes_or_string(tx_id)})
def factoid_submit(self, transaction: Union[bytes, str]):
"""
The factoid-submit API takes a specifically formatted message as bytes or a hex string that includes signatures.
If you have a factom-walletd instance running, you can construct this factoid-submit API call with
compose-transaction which takes easier to construct arguments.
"""
return self._request("factoid-submit", {"transaction": utils.hex_from_bytes_or_string(transaction)})
def directory_block_by_keymr(self, keymr: Union[bytes, str]):
"""
Every directory block has a KeyMR (Key Merkle Root), which can be used to retrieve it.
The response will contain information that can be used to navigate through all transactions (entry
and factoid) within that block. The header of the directory block will contain information regarding
the previous directory block key Merkle root, directory block height, and the timestamp.
"""
return self._request("directory-block", {"keymr": utils.hex_from_bytes_or_string(keymr)})
def send_raw_message(self, message: Union[bytes, str]):
"""
Send a raw hex encoded binary message to the Factom network. This is
mostly just for debugging and testing.
"""
return self._request("send-raw-message", {
"message": utils.hex_from_bytes_or_string(message)
})
def receipt(self, entry_hash: Union[bytes, str], include_raw_entry: bool = False):
"""
Retrieve a receipt providing cryptographically verifiable proof
that information was recorded in the Factom blockchain and that
this was subsequently anchored in the bitcoin blockchain.
"""
return self._request(
"receipt", {"hash": utils.hex_from_bytes_or_string(entry_hash), "includerawentry": include_raw_entry}
)
def entry(self, entry_hash: Union[bytes, str], encode_as_hex: bool = False):
"""
Get an Entry from factomd specified by the Entry Hash.
If `encode_as_hex` is True, content and external ids will be returned as hex strings rather than bytes-objects.
"""
resp = self._request("entry", {"hash": utils.hex_from_bytes_or_string(entry_hash)})
if not encode_as_hex:
resp["extids"] = [bytes.fromhex(x) for x in resp["extids"]]
resp["content"] = bytes.fromhex(resp["content"])
return resp
def new_entry(
self,
factomd: Factomd,
chain_id: Union[bytes, str],
ext_ids: List[Union[bytes, str]],
content: Union[bytes, str],
ec_address: str = None,
sleep: float = 1.0,
):
"""
Shortcut method to create a new entry.
Args:
factomd (Factomd): The `Factomd` instance where the creation message
will be submitted.
chain_id (Union[bytes, str]): Chain ID where entry will be appended.
ext_ids (List[Union[bytes, str]]): A list of external IDs as
bytes-like objects or hex strings.
content (Union[bytes, str]): Entry content as a bytes like object or
hex string.
ec_address (str): Entry credit address to pay with. If not provided,
`self.ec_address` will be used.
sleep (float): Number of seconds to sleep between entry commit and
reveal. Default is 1.0.
Returns:
dict: API result from the final `reveal_chain()` call.
"""
calls = self._request(
"compose-entry",
{
"entry": {
"chainid": utils.hex_from_bytes_or_string(chain_id),
"extids": [utils.hex_from_bytes_or_string(x) for x in ext_ids],
"content": utils.hex_from_bytes_or_string(content),
},
"ecpub": ec_address or self.ec_address,
},
)
factomd.commit_entry(calls["commit"]["params"]["message"])
time.sleep(sleep)
return factomd.reveal_entry(calls["reveal"]["params"]["entry"])
def anchors(self, object_hash: Union[bytes, str] = None, height: int = None):
"""Retrieve the set of anchors for a given object hash or directory block height."""
if object_hash is None:
assert height is not None, "No object_hash provided, height must not be none"
assert height >= 0, "Height must be >= 0"
params = {"height": height}
else:
assert height is None, "Hash provided, height must be None"
params = {"hash": utils.hex_from_bytes_or_string(object_hash)}
return self._request("anchors", params)
def chain_head(self, chain_id: Union[bytes, str]):
return self._request("chain-head", {"chainid": utils.hex_from_bytes_or_string(chain_id)})
def admin_block(self, keymr: Union[bytes, str]):
"""Retrieve a specified admin block given its key Merkle root."""
return self._request("admin-block", {"keymr": utils.hex_from_bytes_or_string(keymr)})
def transaction(self, tx_hash: Union[bytes, str]):
"""Retrieve details of a factoid transaction using a transaction hash (or corresponding transaction id)."""
return self._request("transaction", {"hash": utils.hex_from_bytes_or_string(tx_hash)})
def reveal_entry(self, entry: Union[bytes, str]):
return self._request("reveal-entry", {"entry": utils.hex_from_bytes_or_string(entry)})
def raw_data(self, object_hash: Union[bytes, str]):
"""Retrieve an entry, transaction, or block in raw (marshalled) format."""
return self._request("raw-data", {"hash": utils.hex_from_bytes_or_string(object_hash)})
def commit_entry(self, message: Union[bytes, str]):
return self._request("commit-entry", {"message": utils.hex_from_bytes_or_string(message)})
def factoid_block_by_keymr(self, keymr: Union[bytes, str]):
"""Retrieve a specified factoid block given its key Merkle root."""
return self._request("factoid-block", {"keymr": utils.hex_from_bytes_or_string(keymr)})
def entry_credit_block(self, keymr: Union[bytes, str]):
"""Retrieve a specified entry credit block (including minute markers) given its key Merkle root."""
return self._request("entrycredit-block", {"keymr": utils.hex_from_bytes_or_string(keymr)})
def entry_block(self, keymr: Union[bytes, str]):
"""Retrieve a specified entry block given its Merkle root key. The entry block contains 0 to many entries"""
return self._request("entry-block", {"keymr": utils.hex_from_bytes_or_string(keymr)})
