A small library for reacting to Obyte Autonomous Agent (AA) responses. You watch one or more AA addresses, describe the responses you care about with a chain of filters, and get a callback whenever a matching response appears on the DAG.
It runs inside an ocore/headless-wallet process and uses aabot to read the DAG.
npm install aa-hooks
# or
yarn add aa-hooksocore is a peer dependency (it must be a single shared instance in your app, alongside your headless wallet), so install it too if it isn't already present:
npm install ocoreRequires Node.js 14+ (the test suite requires Node 18+).
const { Hooks } = require("aa-hooks");
// Watch a set of AA addresses
const hooks = new Hooks(["O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ"], {
newEventsOnly: false, // default: false — also process past responses
parallelProcessing: false // default: false — process responses one at a time
});
const onNewSymbol = async (triggerUnit, responseObj) => {
const symbol = triggerUnit.messages.find((m) => m.app === "data")?.payload?.symbol;
console.error("New symbol registered:", symbol);
console.error("Response unit:", responseObj.response_unit);
await hooks.addWatchedAddress("..."); // start watching another AA at runtime
};
// Register a hook: the callback fires only when ALL filters pass
hooks.register(onNewSymbol)
.isSuccess()
.triggerDataContainsKey("symbol")
.triggerDataContainsKey("asset")
.triggerDataContainsKey("drawer")
.not.triggerDataContainsKey("decimals"); // `.not` negates the next filter onlyThe callback receives (triggerUnit, responseObj):
triggerUnit— the full unit that triggered the AA (see the example below), or{}if it can't be read.responseObj— the AA response object (see the example below).
- Filters are combined with AND. A hook fires only if every filter in its chain passes.
.notnegates the next filter only, then the chain continues normally.- Every matching hook fires. If several registered hooks match the same response, all of their callbacks run.
- Serial by default. Responses are processed one at a time; set
parallelProcessing: trueto process them concurrently. - Errors are contained. An error thrown by a filter or a callback is caught and logged — it never freezes processing or stops the other hooks.
- Trigger units are cached per unit hash for the duration of the process, so the same unit is read from the DAG only once no matter how many filters need it.
| Argument | Type | Description |
|---|---|---|
addresses |
string[] |
AA addresses to watch. |
config.newEventsOnly |
boolean |
Default false. When true, only responses with a timestamp at/after construction time are processed. |
config.parallelProcessing |
boolean |
Default false. When true, responses are handled concurrently instead of one at a time. |
Creates a hook and returns its controller so you can chain filters. callback is (triggerUnit, responseObj) => void | Promise<void>.
Loads an AA definition and starts watching the address at runtime. Rejects if the AA definition can't be loaded.
Unregisters the hook: it stops receiving events and its filters are released.
All filters return the controller, so they are chainable. Prefix any filter with .not to negate it.
| Filter | Matches when |
|---|---|
aaAddressIs(address) |
the response is from AA address. |
triggerAddressIs(address) |
the trigger unit was sent by address. |
triggerUnitIs(unit) |
the trigger unit hash equals unit. |
baseAaIs(address) |
the responding AA's base_aa equals address. |
| Filter | Matches when |
|---|---|
isSuccess() |
the response did not bounce (bounced === 0). |
isBounced() |
the response bounced (bounced !== 0). |
| Filter | Matches when |
|---|---|
responseContainsKey(key) |
key exists in the response vars. |
responseKeyIs(key, value) |
responseVars[key] === value. |
responseKeyLessThan(key, value) |
responseVars[key] < value. |
responseKeyMoreThan(key, value) |
responseVars[key] > value. |
| Filter | Matches when |
|---|---|
triggerDataExists() |
the trigger unit has a non-empty data payload. |
triggerDataContainsKey(key) |
key exists in the trigger data. |
triggerDataKeyIs(key, value) |
data[key] === value. |
triggerDataKeyLessThan(key, value) |
data[key] < value. |
triggerDataKeyMoreThan(key, value) |
data[key] > value. |
Note the argument order: asset comes first.
| Filter | Matches when |
|---|---|
sentAmountIs(asset, value, address?) |
the amount of asset sent equals value. |
sentAmountLessThan(asset, value, address?) |
the amount of asset sent is < value. |
sentAmountMoreThan(asset, value, address?) |
the amount of asset sent is > value. |
Note the argument order: value comes first.
| Filter | Matches when |
|---|---|
responseOutputsAmountIs(value, asset, address?) |
the amount of asset paid out equals value. |
responseOutputsAmountLessThan(value, asset, address?) |
the amount of asset paid out is < value. |
responseOutputsAmountMoreThan(value, asset, address?) |
the amount of asset paid out is > value. |
For the amount filters:
valueis an integer in the asset's smallest unit (e.g. bytes for GBYTE).assetis an asset id; use"base","GBYTE", or"bytes"for the base currency.addressis optional — when given, only outputs to that address are summed.
customFilter(filter, metaKeys?) runs your own predicate. It must return a boolean (otherwise it throws). Request extra context via metaKeys:
hooks.register(handler)
.isSuccess()
.customFilter(async (responseObj, meta) => {
const { payload, trigger_unit } = meta; // only the keys you requested
return payload.symbol?.startsWith("ETH");
}, ["payload", "trigger_unit"]) // available meta keys: "payload", "trigger_unit"
.triggerDataContainsKey("symbol");Negates the next filter in the chain:
hooks.register(handler)
.isSuccess()
.not.triggerDataContainsKey("decimals"); // fires when `decimals` is NOT presentExample triggerUnit
{
"version": "3.0t",
"alt": "2",
"messages": [
{
"app": "data",
"payload_location": "inline",
"payload": {
"asset": "tZgXWTAv+1v1Ow4pMEVFFNlZAobGxMm2kIcr2dVR68c=",
"symbol": "ETH3",
"decimals": 8,
"description": "ETH on Obyte"
},
"payload_hash": "SLL9ew+vIImeuk88nh78xav/kNsp5DgvZU/JwW8g+9w="
},
{
"app": "payment",
"payload_location": "inline",
"payload_hash": "aEoZ8aNjru503wcW8D2FtfEVlJ0vI8H138afFegz5kI=",
"payload": {
"inputs": [
{
"unit": "EgJcb2OejlGnCceBGy/ToQMl4AGJpcMfnvzqLA7le+k=",
"message_index": 0,
"output_index": 1
}
],
"outputs": [
{
"address": "O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ",
"amount": 100000000
},
{
"address": "TNM2YRTJOANVGXMCFOH2FBVC3KYHZ4O6",
"amount": 999999047
}
]
}
}
],
"authors": [
{
"address": "TNM2YRTJOANVGXMCFOH2FBVC3KYHZ4O6",
"authentifiers": {
"r": "eypr8bDqB5GGj+yVZgGJajMtUfrI6KxFBFh+olGG6XF8EaBtSsss4sryd45oBU7TZB1L9QWZRJeHKWytoIPQRQ=="
}
}
],
"parent_units": [
"v+Yp106wJ03H5B/iUET6qIL4ZA/urwckH9y2iaRdnN4="
],
"last_ball": "iaI+7i0vUjvxjj5Qyhpv8vcYi8eJE78J5KGRd7ppTSc=",
"last_ball_unit": "Mf1h7ObKs1unBiKCcnluHZjKa6qO+ODdDMMh/zS+wz0=",
"timestamp": 1624754674,
"witness_list_unit": "TvqutGPz3T4Cs6oiChxFlclY92M2MvCvfXR5/FETato=",
"headers_commission": 452,
"payload_commission": 501,
"unit": "o+Xe1O4MfEBz2/3UOPTgc+5PNnpdhEPhhho52Iyf1HM=",
"main_chain_index": 2045972
}Example responseObj
{
"mci": 2045972,
"trigger_address": "TNM2YRTJOANVGXMCFOH2FBVC3KYHZ4O6",
"aa_address": "O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ",
"trigger_unit": "o+Xe1O4MfEBz2/3UOPTgc+5PNnpdhEPhhho52Iyf1HM=",
"bounced": 0,
"response_unit": "qYfdrDF0yFtaXv3iM1r0SBOruHAdp4A1rDhpJwXcC1U=",
"response": {
"responseVars": {
"ETH3": "tZgXWTAv+1v1Ow4pMEVFFNlZAobGxMm2kIcr2dVR68c=",
"tZgXWTAv+1v1Ow4pMEVFFNlZAobGxMm2kIcr2dVR68c=": "ETH3",
"TNM2YRTJOANVGXMCFOH2FBVC3KYHZ4O6_0_ETH3_tZgXWTAv+1v1Ow4pMEVFFNlZAobGxMm2kIcr2dVR68c=": 100000000,
"message": "Your description is now the current"
}
},
"timestamp": 1624754674,
"creation_date": "2021-06-27 00:45:48",
"objResponseUnit": {
"version": "3.0t",
"alt": "2",
"timestamp": 1624754674,
"messages": [
{
"app": "data",
"payload": {
"asset": "tZgXWTAv+1v1Ow4pMEVFFNlZAobGxMm2kIcr2dVR68c=",
"name": "ETH3",
"decimals": 8
},
"payload_location": "inline",
"payload_hash": "gRcVodd+gpMN/AMh0e7QsUhhYD2F04ppNBrMaCDUiKc="
},
{
"app": "payment",
"payload": {
"outputs": [
{
"address": "O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ",
"amount": 99999227
}
],
"inputs": [
{
"unit": "FF7QEM1urqVa3nsbyPga6z6duE3gZK2nU3yG5x7Nkw8=",
"message_index": 1,
"output_index": 0
}
]
},
"payload_location": "inline",
"payload_hash": "6ZJLUc4CleXBDL8E38gUXTsG7oPpebMvCM0PZ0DinWk="
}
],
"authors": [
{
"address": "O6H6ZIFI57X3PLTYHOCVYPP5A553CYFQ"
}
],
"last_ball_unit": "Mf1h7ObKs1unBiKCcnluHZjKa6qO+ODdDMMh/zS+wz0=",
"last_ball": "iaI+7i0vUjvxjj5Qyhpv8vcYi8eJE78J5KGRd7ppTSc=",
"witness_list_unit": "TvqutGPz3T4Cs6oiChxFlclY92M2MvCvfXR5/FETato=",
"parent_units": [
"o+Xe1O4MfEBz2/3UOPTgc+5PNnpdhEPhhho52Iyf1HM="
],
"headers_commission": 350,
"payload_commission": 423,
"unit": "qYfdrDF0yFtaXv3iM1r0SBOruHAdp4A1rDhpJwXcC1U=",
"main_chain_index": 2046004
}
}npm testThe suite uses the built-in Node test runner (node --test) with in-memory mocks of ocore/aabot, so no running node is required.
The default settings are in the library's conf.js, they can be overridden in your project root's conf.js, then in conf.json in the app data folder. The app data folder is:
- macOS:
~/Library/Application Support/<appname> - Linux:
~/.config/<appname> - Windows:
%LOCALAPPDATA%\<appname>
<appname> is name in your package.json.
To support our work, donate through kivach.org.