Merge pull request #494 from CosmWasm/HumanizeAddressFunc

GoAPI renamings

docs/MIGRATING.md

@@ -2,8 +2,23 @@
 
 ## 1.x -> 2.0
 
-- `VM.Create` was removed. Use `VM.StoreCode` instead.
 - The `supportedCapabilities` argument in `NewVM` changed from a comma separated
   list to a list of type `[]string`.
-- Remove `SubcallResult`/`SubcallResponse`. Use `SubMsgResult`/`SubMsgResponse`
-  instead.
+
+## Renamings
+
+This section contains renamed symbols that do not require any further
+explanation. Some of the new names may be available in 1.x already in cases
+where the old name was deprecated.
+
+| Old name                 | New name                    | Note                                                        |
+| ------------------------ | --------------------------- | ----------------------------------------------------------- |
+| `VM.Create`              | `VM.StoreCode`              | StoreCode brings consistency with wasmd naming              |
+| `SubcallResult`          | `SubMsgResult`              | Contracts do not "call" each other but send messages around |
+| `SubcallResponse`        | `SubMsgResponse`            | Contracts do not "call" each other but send messages around |
+| `HumanizeAddress`        | `HumanizeAddressFunc`       | Follow [best practice for naming function types][ft]        |
+| `CanonicalizeAddress`    | `CanonicalizeAddressFunc`   | Follow [best practice for naming function types][ft]        |
+| `GoAPI.HumanAddress`     | `GoAPI.HumanizeAddress`     | Perfer verbs for converters                                 |
+| `GoAPI.CanonicalAddress` | `GoAPI.CanonicalizeAddress` | Perfer verbs for converters                                 |
+
+[ft]: https://stackoverflow.com/a/60073310

internal/api/callbacks.go

@@ -23,8 +23,8 @@ GoError cNext_cgo(iterator_t *ptr, gas_meter_t *gas_meter, uint64_t *used_gas, U
 GoError cNextKey_cgo(iterator_t *ptr, gas_meter_t *gas_meter, uint64_t *used_gas, UnmanagedVector *key, UnmanagedVector *errOut);
 GoError cNextValue_cgo(iterator_t *ptr, gas_meter_t *gas_meter, uint64_t *used_gas, UnmanagedVector *val, UnmanagedVector *errOut);
 // api
-GoError cHumanAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
-GoError cCanonicalAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
+GoError cHumanizeAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
+GoError cCanonicalizeAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
 // and querier
 GoError cQueryExternal_cgo(querier_t *ptr, uint64_t gas_limit, uint64_t *used_gas, U8SliceView request, UnmanagedVector *result, UnmanagedVector *errOut);
 
@@ -363,8 +363,8 @@ func nextPart(ref C.iterator_t, gasMeter *C.gas_meter_t, usedGas *cu64, output *
 }
 
 var api_vtable = C.GoApiVtable{
-	humanize_address:     C.any_function_t(C.cHumanAddress_cgo),
-	canonicalize_address: C.any_function_t(C.cCanonicalAddress_cgo),
+	humanize_address:     C.any_function_t(C.cHumanizeAddress_cgo),
+	canonicalize_address: C.any_function_t(C.cCanonicalizeAddress_cgo),
 }
 
 // contract: original pointer/struct referenced must live longer than C.GoApi struct
@@ -376,8 +376,8 @@ func buildAPI(api *types.GoAPI) C.GoApi {
 	}
 }
 
-//export cHumanAddress
-func cHumanAddress(ptr *C.api_t, src C.U8SliceView, dest *C.UnmanagedVector, errOut *C.UnmanagedVector, used_gas *cu64) (ret C.GoError) {
+//export cHumanizeAddress
+func cHumanizeAddress(ptr *C.api_t, src C.U8SliceView, dest *C.UnmanagedVector, errOut *C.UnmanagedVector, used_gas *cu64) (ret C.GoError) {
 	defer recoverPanic(&ret)
 
 	if dest == nil || errOut == nil {
@@ -390,22 +390,22 @@ func cHumanAddress(ptr *C.api_t, src C.U8SliceView, dest *C.UnmanagedVector, err
 	api := (*types.GoAPI)(unsafe.Pointer(ptr))
 	s := copyU8Slice(src)
 
-	h, cost, err := api.HumanAddress(s)
+	h, cost, err := api.HumanizeAddress(s)
 	*used_gas = cu64(cost)
 	if err != nil {
 		// store the actual error message in the return buffer
 		*errOut = newUnmanagedVector([]byte(err.Error()))
 		return C.GoError_User
 	}
 	if len(h) == 0 {
-		panic(fmt.Sprintf("`api.HumanAddress()` returned an empty string for %q", s))
+		panic(fmt.Sprintf("`api.HumanizeAddress()` returned an empty string for %q", s))
 	}
 	*dest = newUnmanagedVector([]byte(h))
 	return C.GoError_None
 }
 
-//export cCanonicalAddress
-func cCanonicalAddress(ptr *C.api_t, src C.U8SliceView, dest *C.UnmanagedVector, errOut *C.UnmanagedVector, used_gas *cu64) (ret C.GoError) {
+//export cCanonicalizeAddress
+func cCanonicalizeAddress(ptr *C.api_t, src C.U8SliceView, dest *C.UnmanagedVector, errOut *C.UnmanagedVector, used_gas *cu64) (ret C.GoError) {
 	defer recoverPanic(&ret)
 
 	if dest == nil || errOut == nil {
@@ -417,15 +417,15 @@ func cCanonicalAddress(ptr *C.api_t, src C.U8SliceView, dest *C.UnmanagedVector,
 
 	api := (*types.GoAPI)(unsafe.Pointer(ptr))
 	s := string(copyU8Slice(src))
-	c, cost, err := api.CanonicalAddress(s)
+	c, cost, err := api.CanonicalizeAddress(s)
 	*used_gas = cu64(cost)
 	if err != nil {
 		// store the actual error message in the return buffer
 		*errOut = newUnmanagedVector([]byte(err.Error()))
 		return C.GoError_User
 	}
 	if len(c) == 0 {
-		panic(fmt.Sprintf("`api.CanonicalAddress()` returned an empty string for %q", s))
+		panic(fmt.Sprintf("`api.CanonicalizeAddress()` returned an empty string for %q", s))
 	}
 	*dest = newUnmanagedVector(c)
 	return C.GoError_None

internal/api/callbacks_cgo.go

@@ -14,8 +14,8 @@ GoError cNext(iterator_t *ptr, gas_meter_t *gas_meter, uint64_t *used_gas, Unman
 GoError cNextKey(iterator_t *ptr, gas_meter_t *gas_meter, uint64_t *used_gas, UnmanagedVector *key, UnmanagedVector *errOut);
 GoError cNextValue(iterator_t *ptr, gas_meter_t *gas_meter, uint64_t *used_gas, UnmanagedVector *value, UnmanagedVector *errOut);
 // imports (api)
-GoError cHumanAddress(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
-GoError cCanonicalAddress(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
+GoError cHumanizeAddress(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
+GoError cCanonicalizeAddress(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas);
 // imports (querier)
 GoError cQueryExternal(querier_t *ptr, uint64_t gas_limit, uint64_t *used_gas, U8SliceView request, UnmanagedVector *result, UnmanagedVector *errOut);
 
@@ -45,11 +45,11 @@ GoError cNextValue_cgo(iterator_t *ptr, gas_meter_t *gas_meter, uint64_t *used_g
 }
 
 // Gateway functions (api)
-GoError cCanonicalAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas) {
-    return cCanonicalAddress(ptr, src, dest, errOut, used_gas);
+GoError cCanonicalizeAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas) {
+    return cCanonicalizeAddress(ptr, src, dest, errOut, used_gas);
 }
-GoError cHumanAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas) {
-    return cHumanAddress(ptr, src, dest, errOut, used_gas);
+GoError cHumanizeAddress_cgo(api_t *ptr, U8SliceView src, UnmanagedVector *dest, UnmanagedVector *errOut, uint64_t *used_gas) {
+    return cHumanizeAddress(ptr, src, dest, errOut, used_gas);
 }
 
 // Gateway functions (querier)

internal/api/lib.go

@@ -699,17 +699,17 @@ func errorWithMessage(err error, b C.UnmanagedVector) error {
 // to be caused by user data.
 func checkAndPinAPI(api *types.GoAPI, pinner runtime.Pinner) {
 	if api == nil {
-		panic("API must not be nil. If you don't want to provide API functionality, please create an instance that returns an error on every call to HumanAddress() and CanonicalAddress().")
+		panic("API must not be nil. If you don't want to provide API functionality, please create an instance that returns an error on every call to HumanizeAddress() and CanonicalizeAddress().")
 	}
 
-	// func cHumanAddress assumes this is set
-	if api.HumanAddress == nil {
-		panic("HumanAddress in API must not be nil. If you don't want to provide API functionality, please create an instance that returns an error on every call to HumanAddress() and CanonicalAddress().")
+	// func cHumanizeAddress assumes this is set
+	if api.HumanizeAddress == nil {
+		panic("HumanizeAddress in API must not be nil. If you don't want to provide API functionality, please create an instance that returns an error on every call to HumanizeAddress() and CanonicalizeAddress().")
 	}
 
-	// func cCanonicalAddress assums this is set
-	if api.CanonicalAddress == nil {
-		panic("CanonicalAddress in API must not be nil. If you don't want to provide API functionality, please create an instance that returns an error on every call to HumanAddress() and CanonicalAddress().")
+	// func cCanonicalizeAddress assumes this is set
+	if api.CanonicalizeAddress == nil {
+		panic("CanonicalizeAddress in API must not be nil. If you don't want to provide API functionality, please create an instance that returns an error on every call to HumanizeAddress() and CanonicalizeAddress().")
 	}
 
 	pinner.Pin(api) // this pointer is used in Rust (`state` in `C.GoApi`) and must not change

internal/api/mock_failure.go

@@ -8,17 +8,17 @@ import (
 
 /***** Mock types.GoAPI ****/
 
-func MockFailureCanonicalAddress(human string) ([]byte, uint64, error) {
+func MockFailureCanonicalizeAddress(human string) ([]byte, uint64, error) {
 	return nil, 0, fmt.Errorf("mock failure - canonical_address")
 }
 
-func MockFailureHumanAddress(canon []byte) (string, uint64, error) {
+func MockFailureHumanizeAddress(canon []byte) (string, uint64, error) {
 	return "", 0, fmt.Errorf("mock failure - human_address")
 }
 
 func NewMockFailureAPI() *types.GoAPI {
 	return &types.GoAPI{
-		HumanAddress:     MockFailureHumanAddress,
-		CanonicalAddress: MockFailureCanonicalAddress,
+		HumanizeAddress:     MockFailureHumanizeAddress,
+		CanonicalizeAddress: MockFailureCanonicalizeAddress,
 	}
 }

internal/api/mocks.go

@@ -337,7 +337,7 @@ const (
 	CostHuman     uint64 = 550
 )
 
-func MockCanonicalAddress(human string) ([]byte, uint64, error) {
+func MockCanonicalizeAddress(human string) ([]byte, uint64, error) {
 	if len(human) > CanonicalLength {
 		return nil, 0, fmt.Errorf("human encoding too long")
 	}
@@ -346,7 +346,7 @@ func MockCanonicalAddress(human string) ([]byte, uint64, error) {
 	return res, CostCanonical, nil
 }
 
-func MockHumanAddress(canon []byte) (string, uint64, error) {
+func MockHumanizeAddress(canon []byte) (string, uint64, error) {
 	if len(canon) != CanonicalLength {
 		return "", 0, fmt.Errorf("wrong canonical length")
 	}
@@ -363,19 +363,19 @@ func MockHumanAddress(canon []byte) (string, uint64, error) {
 
 func NewMockAPI() *types.GoAPI {
 	return &types.GoAPI{
-		HumanAddress:     MockHumanAddress,
-		CanonicalAddress: MockCanonicalAddress,
+		HumanizeAddress:     MockHumanizeAddress,
+		CanonicalizeAddress: MockCanonicalizeAddress,
 	}
 }
 
 func TestMockApi(t *testing.T) {
 	human := "foobar"
-	canon, cost, err := MockCanonicalAddress(human)
+	canon, cost, err := MockCanonicalizeAddress(human)
 	require.NoError(t, err)
 	assert.Equal(t, CanonicalLength, len(canon))
 	assert.Equal(t, CostCanonical, cost)
 
-	recover, cost, err := MockHumanAddress(canon)
+	recover, cost, err := MockHumanizeAddress(canon)
 	require.NoError(t, err)
 	assert.Equal(t, recover, human)
 	assert.Equal(t, CostHuman, cost)

types/api.go

@@ -1,11 +1,15 @@
 package types
 
 type (
-	HumanizeAddress     func([]byte) (string, uint64, error)
-	CanonicalizeAddress func(string) ([]byte, uint64, error)
+	// HumanizeAddressFunc is a type for functions that convert a canonical address (bytes)
+	// to a human readable address (typically bech32).
+	HumanizeAddressFunc func([]byte) (string, uint64, error)
+	// CanonicalizeAddressFunc is a type for functions that convert a human readable address (typically bech32)
+	// to a canonical address (bytes).
+	CanonicalizeAddressFunc func(string) ([]byte, uint64, error)
 )
 
 type GoAPI struct {
-	HumanAddress     HumanizeAddress
-	CanonicalAddress CanonicalizeAddress
+	HumanizeAddress     HumanizeAddressFunc
+	CanonicalizeAddress CanonicalizeAddressFunc
 }