Add Warp Payload Types

vms/platformvm/warp/payload/README.md

@@ -0,0 +1,44 @@
+# Payload
+
+An Avalanche Unsigned Warp Message already includes a `networkID`, `sourceChainID`, and `payload` field. The `payload` field is parsed into one of the types included in this package to be further handled by the VM.
+
+## AddressedCall
+
+AddressedCall:
+```
++---------------------+--------+----------------------------------+
+|             codecID : uint16 |                          2 bytes |
++---------------------+--------+----------------------------------+
+|              typeID : uint32 |                          4 bytes |
++---------------------+--------+----------------------------------+
+|       sourceAddress : []byte |                 4 + len(address) |
++---------------------+--------+----------------------------------+
+|             payload : []byte |                 4 + len(payload) |
++---------------------+--------+----------------------------------+
+                               | 14 + len(payload) + len(address) |
+                               +----------------------------------+
+```
+
+- `codecID` is the codec version used to serialize the payload and is hardcoded to `0x0000`
+- `typeID` is the payload type identifier and is `0x00000000` for `AddressedCall`
+- `sourceAddress` is the address that sent this message from the source chain
+- `payload` is an arbitrary byte array payload
+
+## BlockHash
+
+BlockHash:
+```
++-----------------+----------+-----------+
+|         codecID :   uint16 |   2 bytes |
++-----------------+----------+-----------+
+|          typeID :   uint32 |   4 bytes |
++-----------------+----------+-----------+
+|       blockHash : [32]byte |  32 bytes |
++-----------------+----------+-----------+
+                             |  38 bytes |
+                             +-----------+
+```
+
+- `codecID` is the codec version used to serialize the payload and is hardcoded to `0x0000`
+- `typeID` is the payload type identifier and is `0x00000001` for `BlockHash`
+- `blockHash` is a blockHash from the `sourceChainID`. A signed block hash payload indicates that the signer has accepted the block on the source chain.

vms/platformvm/warp/payload/addressed_payload.go

@@ -0,0 +1,63 @@
+// Copyright (C) 2019-2023, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package payload
+
+import "fmt"
+
+var _ byteSetter = (*AddressedCall)(nil)
+
+// AddressedCall defines the format for delivering a call across VMs including a
+// source address and a payload.
+// Implementation of destinationAddress can be implemented on top of this payload.
+type AddressedCall struct {
+	SourceAddress []byte `serialize:"true"`
+	Payload       []byte `serialize:"true"`
+
+	bytes []byte
+}
+
+// NewAddressedCall creates a new *AddressedCall and initializes it.
+func NewAddressedCall(sourceAddress []byte, payload []byte) (*AddressedCall, error) {
+	ap := &AddressedCall{
+		SourceAddress: sourceAddress,
+		Payload:       payload,
+	}
+	return ap, ap.initialize()
+}
+
+// ParseAddressedCall converts a slice of bytes into an initialized
+// AddressedCall.
+func ParseAddressedCall(b []byte) (*AddressedCall, error) {
+	var unmarshalledPayloadIntf any
+	if _, err := c.Unmarshal(b, &unmarshalledPayloadIntf); err != nil {
+		return nil, err
+	}
+	payload, ok := unmarshalledPayloadIntf.(*AddressedCall)
+	if !ok {
+		return nil, fmt.Errorf("%w: %T", errWrongType, unmarshalledPayloadIntf)
+	}
+	payload.bytes = b
+	return payload, nil
+}
+
+// initialize recalculates the result of Bytes().
+func (a *AddressedCall) initialize() error {
+	payloadIntf := any(a)
+	bytes, err := c.Marshal(codecVersion, &payloadIntf)
+	if err != nil {
+		return fmt.Errorf("couldn't marshal warp addressed payload: %w", err)
+	}
+	a.bytes = bytes
+	return nil
+}
+
+func (a *AddressedCall) setBytes(bytes []byte) {
+	a.bytes = bytes
+}
+
+// Bytes returns the binary representation of this payload. It assumes that the
+// payload is initialized from either NewAddressedCall or ParseAddressedCall.
+func (a *AddressedCall) Bytes() []byte {
+	return a.bytes
+}

vms/platformvm/warp/payload/block_hash_payload.go

@@ -0,0 +1,63 @@
+// Copyright (C) 2019-2023, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package payload
+
+import (
+	"fmt"
+
+	"github.com/ava-labs/avalanchego/ids"
+)
+
+var _ byteSetter = (*BlockHash)(nil)
+
+// BlockHash includes the block hash
+type BlockHash struct {
+	BlockHash ids.ID `serialize:"true"`
+
+	bytes []byte
+}
+
+// NewBlockHash creates a new *BlockHash and initializes it.
+func NewBlockHash(blockHash ids.ID) (*BlockHash, error) {
+	bhp := &BlockHash{
+		BlockHash: blockHash,
+	}
+	return bhp, bhp.initialize()
+}
+
+// ParseBlockHash converts a slice of bytes into an initialized
+// BlockHash
+func ParseBlockHash(b []byte) (*BlockHash, error) {
+	var unmarshalledPayloadIntf any
+	if _, err := c.Unmarshal(b, &unmarshalledPayloadIntf); err != nil {
+		return nil, err
+	}
+	payload, ok := unmarshalledPayloadIntf.(*BlockHash)
+	if !ok {
+		return nil, fmt.Errorf("%w: %T", errWrongType, unmarshalledPayloadIntf)
+	}
+	payload.bytes = b
+	return payload, nil
+}
+
+// initialize recalculates the result of Bytes().
+func (b *BlockHash) initialize() error {
+	payloadIntf := any(b)
+	bytes, err := c.Marshal(codecVersion, &payloadIntf)
+	if err != nil {
+		return fmt.Errorf("couldn't marshal block hash payload: %w", err)
+	}
+	b.bytes = bytes
+	return nil
+}
+
+func (b *BlockHash) setBytes(bytes []byte) {
+	b.bytes = bytes
+}
+
+// Bytes returns the binary representation of this payload. It assumes that the
+// payload is initialized from either NewBlockHash or ParseBlockHash.
+func (b *BlockHash) Bytes() []byte {
+	return b.bytes
+}

vms/platformvm/warp/payload/codec.go

@@ -0,0 +1,64 @@
+// Copyright (C) 2019-2023, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package payload
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/ava-labs/avalanchego/codec"
+	"github.com/ava-labs/avalanchego/codec/linearcodec"
+	"github.com/ava-labs/avalanchego/utils/units"
+	"github.com/ava-labs/avalanchego/utils/wrappers"
+)
+
+var errWrongType = errors.New("wrong payload type")
+
+const (
+	codecVersion = 0
+
+	MaxMessageSize = 24 * units.KiB
+
+	// Note: Modifying this variable can have subtle implications on memory
+	// usage when parsing malformed payloads.
+	MaxSliceLen = 24 * units.KiB
+)
+
+// Codec does serialization and deserialization for Warp messages.
+var c codec.Manager
+
+func init() {
+	c = codec.NewManager(MaxMessageSize)
+	lc := linearcodec.NewCustomMaxLength(MaxSliceLen)
+
+	errs := wrappers.Errs{}
+	errs.Add(
+		lc.RegisterType(&AddressedCall{}),
+		lc.RegisterType(&BlockHash{}),
+		c.RegisterCodec(codecVersion, lc),
+	)
+	if errs.Errored() {
+		panic(errs.Err)
+	}
+}
+
+// byteSetter provides an interface to set the bytes of an underlying type to [b]
+// after unmarshalling into that type.
+type byteSetter interface {
+	setBytes(b []byte)
+}
+
+func Parse(bytes []byte) (byteSetter, error) {
+	var intf interface{}
+	if _, err := c.Unmarshal(bytes, &intf); err != nil {
+		return nil, err
+	}
+
+	payload, ok := intf.(byteSetter)
+	if !ok {
+		return nil, fmt.Errorf("%w: %T", errWrongType, intf)
+	}
+	payload.setBytes(bytes)
+	return payload, nil
+}

vms/platformvm/warp/payload/payload_test.go

@@ -0,0 +1,143 @@
+// Copyright (C) 2019-2023, Ava Labs, Inc. All rights reserved.
+// See the file LICENSE for licensing terms.
+
+package payload
+
+import (
+	"encoding/base64"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	"github.com/ava-labs/avalanchego/codec"
+	"github.com/ava-labs/avalanchego/ids"
+	"github.com/ava-labs/avalanchego/utils"
+)
+
+func TestAddressedCall(t *testing.T) {
+	require := require.New(t)
+	shortID := ids.GenerateTestShortID()
+
+	addressedPayload, err := NewAddressedCall(
+		shortID[:],
+		[]byte{1, 2, 3},
+	)
+	require.NoError(err)
+
+	addressedPayloadBytes := addressedPayload.Bytes()
+	addressedPayload2, err := ParseAddressedCall(addressedPayloadBytes)
+	require.NoError(err)
+	require.Equal(addressedPayload, addressedPayload2)
+}
+
+func TestParseAddressedCallJunk(t *testing.T) {
+	require := require.New(t)
+	_, err := ParseAddressedCall(utils.RandomBytes(1024))
+	require.ErrorIs(err, codec.ErrUnknownVersion)
+}
+
+func TestParseAddressedCall(t *testing.T) {
+	require := require.New(t)
+	base64Payload := "AAAAAAAAAAAAEAECAwAAAAAAAAAAAAAAAAAAAAADCgsM"
+	payload := &AddressedCall{
+		SourceAddress: []byte{1, 2, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
+		Payload:       []byte{10, 11, 12},
+	}
+
+	require.NoError(payload.initialize())
+
+	require.Equal(base64Payload, base64.StdEncoding.EncodeToString(payload.Bytes()))
+
+	parsedPayload, err := ParseAddressedCall(payload.Bytes())
+	require.NoError(err)
+	require.Equal(payload, parsedPayload)
+}
+
+func TestBlockHash(t *testing.T) {
+	require := require.New(t)
+
+	blockHashPayload, err := NewBlockHash(ids.GenerateTestID())
+	require.NoError(err)
+
+	blockHashPayloadBytes := blockHashPayload.Bytes()
+	blockHashPayload2, err := ParseBlockHash(blockHashPayloadBytes)
+	require.NoError(err)
+	require.Equal(blockHashPayload, blockHashPayload2)
+}
+
+func TestParseBlockHashJunk(t *testing.T) {
+	require := require.New(t)
+	_, err := ParseBlockHash(utils.RandomBytes(1024))
+	require.ErrorIs(err, codec.ErrUnknownVersion)
+}
+
+func TestParseBlockHash(t *testing.T) {
+	require := require.New(t)
+	base64Payload := "AAAAAAABBAUGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+	payload := &BlockHash{
+		BlockHash: ids.ID{4, 5, 6},
+	}
+
+	require.NoError(payload.initialize())
+
+	require.Equal(base64Payload, base64.StdEncoding.EncodeToString(payload.Bytes()))
+
+	parsedPayload, err := ParseBlockHash(payload.Bytes())
+	require.NoError(err)
+	require.Equal(payload, parsedPayload)
+}
+
+func TestParseWrongPayloadType(t *testing.T) {
+	require := require.New(t)
+	blockHashPayload, err := NewBlockHash(ids.GenerateTestID())
+	require.NoError(err)
+
+	shortID := ids.GenerateTestShortID()
+	addressedPayload, err := NewAddressedCall(
+		shortID[:],
+		[]byte{1, 2, 3},
+	)
+	require.NoError(err)
+
+	_, err = ParseAddressedCall(blockHashPayload.Bytes())
+	require.ErrorIs(err, errWrongType)
+
+	_, err = ParseBlockHash(addressedPayload.Bytes())
+	require.ErrorIs(err, errWrongType)
+}
+
+func TestParseJunk(t *testing.T) {
+	require := require.New(t)
+	_, err := Parse(utils.RandomBytes(1024))
+	require.ErrorIs(err, codec.ErrUnknownVersion)
+}
+
+func TestParsePayload(t *testing.T) {
+	require := require.New(t)
+	base64BlockHashPayload := "AAAAAAABBAUGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
+	blockHashPayload := &BlockHash{
+		BlockHash: ids.ID{4, 5, 6},
+	}
+
+	require.NoError(blockHashPayload.initialize())
+
+	require.Equal(base64BlockHashPayload, base64.StdEncoding.EncodeToString(blockHashPayload.Bytes()))
+
+	parsedBlockHashPayload, err := Parse(blockHashPayload.Bytes())
+	require.NoError(err)
+	require.Equal(blockHashPayload, parsedBlockHashPayload)
+
+	base64AddressedPayload := "AAAAAAAAAAAAEAECAwAAAAAAAAAAAAAAAAAAAAADCgsM"
+	addressedPayload := &AddressedCall{
+		SourceAddress: []byte{1, 2, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0},
+		Payload:       []byte{10, 11, 12},
+	}
+
+	require.NoError(addressedPayload.initialize())
+
+	require.Equal(base64AddressedPayload, base64.StdEncoding.EncodeToString(addressedPayload.Bytes()))
+
+	parsedAddressedPayload, err := Parse(addressedPayload.Bytes())
+	require.NoError(err)
+	require.Equal(addressedPayload, parsedAddressedPayload)
+}