0057 XLS-57d: Hook Identification with hooks.toml

[zgrguric]

Hook identification

Abstract

Identification of hooks, its origin, and author can be done using hooks.toml file.

There is need for easy and standardized way for Hook Author to Identify their own hooks for numerous reasons such as public trust, source-to-hook verification, access for auditors, etc.

Hooks in compiled state can be looked up on the Ledger by its HASH. Its WASM, originating rAddress and usage can be extracted. Beyond that - original source code, hook motivation and any outside references are not obtainable.

If hook is open-sourced (advised) Hook's source code can be re-compiled and detected if the same hook HASH comes from that source. Hook source code is can be shared via GitHub project or Gist link, although can be other web URL.

TOML Web location

Hook TOML web URL will be composable by looking up Hook by its HASH on Ledger, then finding out hook creator rAddress. From that rAddress get Domain (acme.com) from account settings and compose hooks.toml path:

https://acme.com/.well-known/hooks.toml

Note on Hook’s author: As hook definition can be created then destroyed (when last account uninstalls it) then again created, that might result in different author of same hook at later point in time. TOML contains account field to verify this ownership relation.

TOML hosting rules

Serving TOML file should follow standard practices as described here
See: Protocol, Content-Type, CORS…

hooks.toml sample

[METADATA]
modified = 2023-12-17T08:00:00.000Z

# Optional Organization block (as seen in other tomls)
[ORGANIZATION]
name="ACME Corp."
website="https://acme.com"

# Optional Principal block(s) (as seen in other tomls)
[[PRINCIPALS]]
name = "Name Surname"
email = "[email protected]"
twitter = "@acme"

# Required Hook block(s)
[[HOOKS]]
hook = "5EDF643..."
related_hooks = ['7JFDE67D...']
account = "rAccount1...."
network_id = 21337
title = "Firewall hook (v1)"
descr = "This is firewall hook. We only maintain this on xahau network, mainnet and testnet."
icon = "https://acme.com/images/hookicon.png"
source = "https://github.com/acme/firewall-hook/releases/tag/v1.0.0"
abi = ""

[[HOOKS]]
hook = "7JFDE67D..."
related_hooks = ['5EDF643...']
account = "rAccount1...."
network_id = 21337
title = "Firewall hook (v2)"
descr = "This is firewall hook. We only maintain this on xahau network, mainnet and testnet."
icon = "https://acme.com/images/hookicon.png"
source = "https://github.com/acme/firewall-hook/releases/tag/v2.0.0"
abi = ""

[[HOOKS]]
hook = "5EDF643..."
account = "rAccount2...."
network_id = 21338
title = "Firewall hook"
descr = "This is firewall hook. We only maintain this on xahau network, mainnet and testnet."
icon = "https://acme.com/images/hookicon2.png"
source = "https://github.com/acme/firewall-hook"
abi = ""

[[HOOKS]]
hook = "7CDA891..."
account = "rAccount3...."
network_id = 0
title = "Piggy savings hook"
descr = "This hook does this and that... We only maintain this on XRP mainnet Ledger."
source = "https://github.com/acme/savings-hook"
abi = ""

# End of file

Fields description

[[HOOKS]] block needs to have minimally following fields hook, account, network_id, title, descr, and source.
Additional optional fields are: related_hooks, icon

hook
This is hook hash.

related_hooks (omittable)
Array. A list of hook hashes that are related to subject Hook. Good place to link other versions of same Hook. Hook processors^[1] can read this field and render list of links to those related hooks.

network_id
This is network ID author of this hook claims it created and maintains hook on specified network.
List of networks is:

• 0 XRPL mainnet
• 1 XRPL testnet
• 2 XRPL devnet
• 21337 Xahau mainnet
• 21338 Xahau testnet

account
rAccount which created this a hook (first installed - this means HookDefinition was created) must match with state on ledger.

Paired with network_id this is second part of hook ownership verification. If rAddress on ledger which created HookDefinition matches one in TOML then this hook ownership is verified.

This is mandatory to prevent 'hijacking' ownership claim of the hook along with account field.

title
This is short title of a hook no more than 50 characters is recommended. (text only)

descr
Long description of a hook, leave empty ("") if not applicable.. (text only)

source
Source link to hook source, leave empty ("") if you do not wan't to share source but it is ADVISED you to do so.

abi
Location to the ABI Specification. (TBA)

icon (omittable)
This is URL to image, a valid square icon file, recommended 512x512px of size. WEBP recommended, accepted: PNG, GIF, JP(E)G,SVG. Developer needs to host this image for availability.

Additional notes

This setup allows differenting hooks by network, and creator account, in sample above first two HOOKS blocks reference to same hook, but indicates different networks (mainnet and testnet) which have two different rAccounts, "ACME Corp." maintains.

Annotations

^[1] Hook processor - a website or app which displays hook information by consuming this TOML file (web explorers etc...)

Changes

• added icon field
• added abi field
• added related_hooks field

[WietseWind]

Wonderful idea. Love the Hook Hash » Creator account » Domain field » TOML location idea :)

Some thoughts about fields to incorporate in the spec. right from the start (?)

Per Hook:

• Add field for ICON (PNG 512 preferred?)
• Add field for ABI location (reserved for future use)

[rsteimen]

A link between a hook binary and its source code is very helpful for verification. Thank you for this idea!

To verify whether a hook binary matches a specific source code, it's not mandatory to know the identity of the entity publishing a hook (rAddress). With privacy and minimizing public data footprint in mind, we should not link to a specific entity as default.
However, since your suggestion is always optional and is a self-declaration, my concerns should not be a problem.

I'd suggest to use specific release/version urls as examples for "source". A given hook binary is only binary equal with one specific state of a given source code.

[zgrguric]

Thank you for your input, about hook versioning (changes in source code) will yield new Hook hash, just simply create new hook block in toml and change title and description, as you can see in example below, both hooks are same 'project' on GitHub, I changed source URL-s to point to specific project release tag, this all depends how will developer link their source URL, I think this is good practice.

# Required Hook block(s)
[[HOOKS]]
hook = "5EDF643..."
account = "rAccount1...."
network_id = 21337
title = "Firewall hook (v1)"
descr = "This is firewall hook. We only maintain this on xahau network, mainnet and testnet."
source = "https://github.com/acme/firewall-hook/releases/tag/v1.0.0"

[[HOOKS]]
hook = "7JFDE67D..."
account = "rAccount1...."
network_id = 21337
title = "Firewall hook (v2)"
descr = "This is firewall hook. We only maintain this on xahau network, mainnet and testnet."
source = "https://github.com/acme/firewall-hook/releases/tag/v2.0.0"