feat: bech32 Address Hooks (#10613)

closes: #10614 refs: #10249 #10250 ## Description Pack a bech32 "base address" (like "agoric1...") plus HTTP query string "hook parameter" bytes into a bech32 "address hook". These address hooks are bech32-encoded (i.e., all of their data is encoded and part of the bech32 checksum), but they may be up to 1024 characters in length (instead of the default 90-character length limit). ### Example ```js import { encodeAddressHook, decodeAddressHook, } from '@agoric/cosmic-proto/address-hooks.js'; const baseAddress = 'agoric1qqp0e5ys'; const query = { key: 'value', foo: ['bar', 'baz'] }; const addressHook = encodeAddressHook(baseAddress, query); // 'agoric10rchqqplvehk70tzv9ezven0du7kyct6ye4k27faweskcat9qqqstnf2eq' addressHook.startsWith('agoric10rch'); // true const decoded = decodeAddressHook(addressHook); // { // baseAddress: 'agoric1qqp0e5ys', // query: [Object: null prototype] { foo: [ 'bar', 'baz' ], key: 'value' } // } ``` ### Encoding Specifically, an address hook looks like "agoric10rch...", and its binary payload consists of: | offset | 0 | 3 | 3+len(baseAddress) | len(payload)-2 | | ------ | ----- | ----------- | ------------------ | ---------------- | | data | magic | baseAddress | hookData | len(baseAddress) | `magic` is a 3-byte prefix that identifies a hooked address and its version nibble, whose value is 4 bits (between 0 and 0xf (15)). Currently, the only supported version is 0. ```js 0x78, 0xf1, (0x70 | ADDRESS_HOOK_VERSION), ``` This magic prefix encodes as `0rch`, regardless of the version or HRP (e.g. `'agoric10rch<rest of payload as bech32><bech32 checksum>'`). ### Security Considerations Improves robustness of address hook extraction with magic bytes and version nibble, as well as length validation. ### Scaling Considerations n/a ### Documentation Considerations Needs to be documented as part of Orch Core Address Hooks. ### Testing Considerations Should be tested as part of a regular contract. Already verified that encoding/decoding unit tests can pass in a JS compartment without any special powers. ### Upgrade Considerations Layered to facilitate the construction of arbitrary hookData, not just URL query strings. Should be extensible if needed.
Agoric · Dec 11, 2024 · 945fef1 · 945fef1
2 parents 5affa34 + c8ad417
commit 945fef1
Show file tree

Hide file tree

Showing 13 changed files with 748 additions and 79 deletions.
diff --git a/a3p-integration/proposals/s:stake-bld/yarn.lock b/a3p-integration/proposals/s:stake-bld/yarn.lock
@@ -99,6 +99,8 @@ __metadata:
   dependencies:
     "@endo/base64": "npm:^1.0.9"
     "@endo/init": "npm:^1.1.7"
+    bech32: "npm:^2.0.0"
+    query-string: "npm:^9.1.1"
   languageName: node
   linkType: soft
 
@@ -1835,6 +1837,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"bech32@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "bech32@npm:2.0.0"
+  checksum: 10c0/45e7cc62758c9b26c05161b4483f40ea534437cf68ef785abadc5b62a2611319b878fef4f86ddc14854f183b645917a19addebc9573ab890e19194bc8f521942
+  languageName: node
+  linkType: hard
+
 "better-sqlite3@npm:^9.1.1":
   version: 9.4.3
   resolution: "better-sqlite3@npm:9.4.3"
@@ -2362,6 +2371,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"decode-uri-component@npm:^0.4.1":
+  version: 0.4.1
+  resolution: "decode-uri-component@npm:0.4.1"
+  checksum: 10c0/a180bbdb5398ec8270d236a3ac07cb988bbf6097428481780b85840f088951dc0318a8d8f9d56796e1a322b55b29859cea29982f22f9b03af0bc60974c54e591
+  languageName: node
+  linkType: hard
+
 "decompress-response@npm:^6.0.0":
   version: 6.0.0
   resolution: "decompress-response@npm:6.0.0"
@@ -2777,6 +2793,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"filter-obj@npm:^5.1.0":
+  version: 5.1.0
+  resolution: "filter-obj@npm:5.1.0"
+  checksum: 10c0/716e8ad2bc352e206556b3e5695b3cdff8aab80c53ea4b00c96315bbf467b987df3640575100aef8b84e812cf5ea4251db4cd672bbe33b1e78afea88400c67dd
+  languageName: node
+  linkType: hard
+
 "find-up@npm:^6.0.0":
   version: 6.3.0
   resolution: "find-up@npm:6.3.0"
@@ -4425,6 +4448,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"query-string@npm:^9.1.1":
+  version: 9.1.1
+  resolution: "query-string@npm:9.1.1"
+  dependencies:
+    decode-uri-component: "npm:^0.4.1"
+    filter-obj: "npm:^5.1.0"
+    split-on-first: "npm:^3.0.0"
+  checksum: 10c0/16481f17754f660aec3cae7abb838a70e383dfcf152414d184e0d0f81fae426acf112b4d51bf754f9c256eaf83ba4241241ba907c8d58b6ed9704425e1712e8c
+  languageName: node
+  linkType: hard
+
 "queue-microtask@npm:^1.2.2":
   version: 1.2.3
   resolution: "queue-microtask@npm:1.2.3"
@@ -4818,6 +4852,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"split-on-first@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "split-on-first@npm:3.0.0"
+  checksum: 10c0/a1262eae12b68de235e1a08e011bf5b42c42621985ddf807e6221fb1e2b3304824913ae7019f18436b96b8fab8aef5f1ad80dedd2385317fdc51b521c3882cd0
+  languageName: node
+  linkType: hard
+
 "sprintf-js@npm:~1.0.2":
   version: 1.0.3
   resolution: "sprintf-js@npm:1.0.3"

diff --git a/a3p-integration/proposals/z:acceptance/yarn.lock b/a3p-integration/proposals/z:acceptance/yarn.lock
@@ -99,6 +99,8 @@ __metadata:
   dependencies:
     "@endo/base64": "npm:^1.0.9"
     "@endo/init": "npm:^1.1.7"
+    bech32: "npm:^2.0.0"
+    query-string: "npm:^9.1.1"
   languageName: node
   linkType: soft
 
@@ -1989,6 +1991,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"bech32@npm:^2.0.0":
+  version: 2.0.0
+  resolution: "bech32@npm:2.0.0"
+  checksum: 10c0/45e7cc62758c9b26c05161b4483f40ea534437cf68ef785abadc5b62a2611319b878fef4f86ddc14854f183b645917a19addebc9573ab890e19194bc8f521942
+  languageName: node
+  linkType: hard
+
 "better-sqlite3@npm:^9.1.1, better-sqlite3@npm:^9.6.0":
   version: 9.6.0
   resolution: "better-sqlite3@npm:9.6.0"
@@ -2543,6 +2552,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"decode-uri-component@npm:^0.4.1":
+  version: 0.4.1
+  resolution: "decode-uri-component@npm:0.4.1"
+  checksum: 10c0/a180bbdb5398ec8270d236a3ac07cb988bbf6097428481780b85840f088951dc0318a8d8f9d56796e1a322b55b29859cea29982f22f9b03af0bc60974c54e591
+  languageName: node
+  linkType: hard
+
 "decompress-response@npm:^6.0.0":
   version: 6.0.0
   resolution: "decompress-response@npm:6.0.0"
@@ -3204,6 +3220,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"filter-obj@npm:^5.1.0":
+  version: 5.1.0
+  resolution: "filter-obj@npm:5.1.0"
+  checksum: 10c0/716e8ad2bc352e206556b3e5695b3cdff8aab80c53ea4b00c96315bbf467b987df3640575100aef8b84e812cf5ea4251db4cd672bbe33b1e78afea88400c67dd
+  languageName: node
+  linkType: hard
+
 "find-up-simple@npm:^1.0.0":
   version: 1.0.0
   resolution: "find-up-simple@npm:1.0.0"
@@ -5357,6 +5380,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"query-string@npm:^9.1.1":
+  version: 9.1.1
+  resolution: "query-string@npm:9.1.1"
+  dependencies:
+    decode-uri-component: "npm:^0.4.1"
+    filter-obj: "npm:^5.1.0"
+    split-on-first: "npm:^3.0.0"
+  checksum: 10c0/16481f17754f660aec3cae7abb838a70e383dfcf152414d184e0d0f81fae426acf112b4d51bf754f9c256eaf83ba4241241ba907c8d58b6ed9704425e1712e8c
+  languageName: node
+  linkType: hard
+
 "queue-microtask@npm:^1.2.2":
   version: 1.2.3
   resolution: "queue-microtask@npm:1.2.3"
@@ -5905,6 +5939,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"split-on-first@npm:^3.0.0":
+  version: 3.0.0
+  resolution: "split-on-first@npm:3.0.0"
+  checksum: 10c0/a1262eae12b68de235e1a08e011bf5b42c42621985ddf807e6221fb1e2b3304824913ae7019f18436b96b8fab8aef5f1ad80dedd2385317fdc51b521c3882cd0
+  languageName: node
+  linkType: hard
+
 "sprintf-js@npm:^1.1.3":
   version: 1.1.3
   resolution: "sprintf-js@npm:1.1.3"

diff --git a/golang/cosmos/x/vtransfer/types/baseaddr.go → golang/cosmos/types/address_hooks.go b/golang/cosmos/x/vtransfer/types/baseaddr.go → golang/cosmos/types/address_hooks.go
@@ -1,11 +1,11 @@
 package types
 
 import (
+	"bytes"
 	"fmt"
-	"net/url"
-	"strings"
 
 	"github.com/cosmos/cosmos-sdk/codec"
+	"github.com/cosmos/cosmos-sdk/types/bech32"
 
 	transfertypes "github.com/cosmos/ibc-go/v6/modules/apps/transfer/types"
 	clienttypes "github.com/cosmos/ibc-go/v6/modules/core/02-client/types"
@@ -18,48 +18,97 @@ type AddressRole string
 const (
 	RoleSender   AddressRole = "Sender"
 	RoleReceiver AddressRole = "Receiver"
+
+	AddressHookVersion     = 0
+	BaseAddressLengthBytes = 2
 )
 
-func trimSlashPrefix(s string) string {
-	return strings.TrimPrefix(s, "/")
+// AddressHookMagic is a magic byte prefix that identifies a hooked address.
+// Chosen to make bech32 address hooks that look like "agoric10rch..."
+var AddressHookMagic = []byte{0x78, 0xf1, 0x70 | AddressHookVersion}
+
+func init() {
+	if AddressHookVersion&0x0f != AddressHookVersion {
+		panic(fmt.Sprintf("AddressHookVersion must be less than 0x10, got 0x%x", AddressHookVersion))
+	}
 }
 
-// ExtractBaseAddress extracts the base address from a parameterized address.
-// It removes all subpath and query components from addr.
+// ExtractBaseAddress extracts the base address from an Address Hook.  It
+// returns addr verbatim if it is not an Address Hook.
 func ExtractBaseAddress(addr string) (string, error) {
-	parsed, err := url.Parse(addr)
+	baseAddr, _, err := SplitHookedAddress(addr)
 	if err != nil {
 		return "", err
 	}
+	return baseAddr, nil
+}
+
+// SplitHookedAddress splits a hooked address into its base address and hook data.
+// For the JS implementation, look at @agoric/cosmic-proto/src/address-hooks.js.
+func SplitHookedAddress(addr string) (string, []byte, error) {
+	prefix, payload, err := bech32.DecodeAndConvert(addr)
+	if err != nil {
+		return "", []byte{}, err
+	}
 
-	// Specify the fields and values we expect.  Unspecified fields will only
-	// match if they are zero values in order to be robust against extensions to
-	// the url.URL struct.
-	//
-	// Remove leading slashes from the path fields so that only parsed relative
-	// paths match the expected test.
-	expected := url.URL{
-		Path:        trimSlashPrefix(parsed.Path),
-		RawPath:     trimSlashPrefix(parsed.RawPath),
-		RawQuery:    parsed.RawQuery,
-		Fragment:    parsed.Fragment,
-		RawFragment: parsed.RawFragment,
+	bz := bytes.TrimPrefix(payload, AddressHookMagic)
+	if len(bz) == len(payload) {
+		// Return an unhooked address.
+		return addr, []byte{}, nil
+	}
 
-		// Skip over parsing control flags.
-		ForceQuery: parsed.ForceQuery,
-		OmitHost:   parsed.OmitHost,
+	if len(bz) < BaseAddressLengthBytes {
+		return "", []byte{}, fmt.Errorf("hooked address must have at least %d bytes", BaseAddressLengthBytes)
 	}
 
-	if *parsed != expected {
-		return "", fmt.Errorf("address must be relative path with optional query and fragment, got %s", addr)
+	b := 0
+	for i := BaseAddressLengthBytes - 1; i >= 0; i -= 1 {
+		byteVal := bz[len(bz)-1-i]
+		b <<= 8
+		b |= int(byteVal)
 	}
 
-	baseAddr, _, _ := strings.Cut(expected.Path, "/")
-	if baseAddr == "" {
-		return "", fmt.Errorf("base address cannot be empty")
+	payloadEnd := len(bz) - BaseAddressLengthBytes
+	if b > payloadEnd {
+		return "", []byte{}, fmt.Errorf("base address length 0x%x is longer than payload end 0x%x", b, payloadEnd)
 	}
 
-	return baseAddr, nil
+	baseAddressBuf := bz[0:b]
+	baseAddress, err := bech32.ConvertAndEncode(prefix, baseAddressBuf)
+	if err != nil {
+		return "", []byte{}, err
+	}
+
+	return baseAddress, bz[b:payloadEnd], nil
+}
+
+// JoinHookedAddress joins a base bech32 address with hook data to create a
+// hooked bech32 address.
+// For the JS implementation, look at @agoric/cosmic-proto/src/address-hooks.js
+func JoinHookedAddress(baseAddr string, hookData []byte) (string, error) {
+	prefix, bz, err := bech32.DecodeAndConvert(baseAddr)
+	if err != nil {
+		return "", err
+	}
+
+	b := len(bz)
+	maxB := 1<<(8*BaseAddressLengthBytes-1) + 1
+	if b > maxB {
+		return "", fmt.Errorf("base address length 0x%x is longer than the maximum 0x%x", b, maxB)
+	}
+
+	payload := make([]byte, 0, len(AddressHookMagic)+b+len(hookData)+BaseAddressLengthBytes)
+	payload = append(payload, AddressHookMagic...)
+	payload = append(payload, bz...)
+	payload = append(payload, hookData...)
+	baLen := make([]byte, BaseAddressLengthBytes)
+	for i := BaseAddressLengthBytes - 1; i >= 0; i -= 1 {
+		baLen[i] = byte(b)
+		b >>= 8
+	}
+	payload = append(payload, baLen...)
+
+	return bech32.ConvertAndEncode(prefix, payload)
 }
 
 // extractBaseTransferData returns the base address from the transferData.Sender