# Lightning Wire Messages
A crate defining serialization and deserialization for lightning wire messages into rust structs.

## Usage
This crate defines the following traits:

### WireItem
- Implemented for all wire types.
- Convenience pairing for `WireItemWriter` and `WireItemReader`

#### WireItemWriter
- Requires `encode`.
- Allows an item to be written to the wire.

#### WireItemReader
- Requires `decode`
- Allows an item to be read from the wire.

### TLVWireItem
- Convenience pairing for `TLVWireItemWriter` and `TLVWireItemReader`
- Blanket implementation for WireItem

#### TLVWireItemWriter
- Requires `encode`.
- Provides `encode_tlv`.

#### TLVWireItemReader
- Requires `decode`.
- Provides `decode_tlv`.

### WireMessage
- Implemented for any struct that is a lightning wire message type.
- Convenience pairing for `WireMessageWriter` and `WireMessageReader`.
- Has methods for serialization and deserialization. 
- If `check_type` is false for `decode`, it is expecting the message without the first 2 bytes indicating the message type.
- If it is true, it will read in the first 2 bytes and verify it matches the message type, otherwise it will return `std::io::ErrorKind::InvalidData`.

#### WireMessageWriter
- Requires `encode`.

#### WireMessageReader
- Requires `decode`.

### AnyWireMessage
- Can be derived for any enum that is an arbitrary subset of all types that implement `WireMessage`. 
- It will use the first 2 bytes of the message to determine which variant to deserialize into.

#### AnyWireMessageWriter
- Can be derived for any enum that is an arbitrary subset of all types that implement `WireMessageWriter`. 

#### AnyWireMessageReader
- Can be derived for any enum that is an arbitrary subset of all types that implement `WireMessageReader`. 

## Contributing
Most lightning messages can be trivially implemented using the following derive macros:

### WireMessage
- Optionally can derive only `WireMessageWriter` or `WireMessageReader`.

#### Requirements
 - Requires attribute: `#[msg_type = 123]` which defines the 2 byte number used to uniquely identify the message type.
 - The type of each non-tlv field must implement `WireItemWriter + WireItemReader`.
    - For `WireMessageWriter`, only requires `WireItemWriter`.
    - For `WireMessageReader`, only requires `WireItemReader`.
 - Fields can be tagged with the `#[tlv_type = 123]` attribute.
 - TLV field numbers must be monotonically increasing.
 - TLV fields must be after non-TLV fields.
 - TLV fields must be an `Option<T> where T: TLVWireItemWriter + TLVWireItemReader`.
    - For `WireMessageWriter`, only requires `TLVWireItemWriter`.
    - For `WireMessageReader`, only requires `TLVWireItemReader`.

### AnyWireMessage
- Optionally can derive only `AnyWireMessageWriter` or `AnyWireMessageReader`

#### Requirements
 - Must be an enum.
 - Each variant must contain a single unnamed field that implements `WireMessageWriter + WireMessageReader`.
   - For `AnyWireMessageWriter`, only requires `WireMessageWriter`.
   - For `AnyWireMessageReader`, only requires `WireMessageReader`.

## Benchmark
Tested 1,000,000 serializations and deserializations of the `watchtower::Init` message, for both this crate and lnd with the following results:
 - lightning-wire-msgs: `387.640625ms`
 - lnd: `1.349666231s`

Code for lnd benchmark can be found at `bench/bench.go`.

Code for crate benchmark can be found at the end of `src/lib.rs`.

I urge anyone else to verify these benchmarks, however I am fairly confident at this point that my crate cuts serialization + deserialization time down by about 70%.