add connect

Author: barnjamin

DESIGN.md

@@ -10,7 +10,7 @@ To address this goal, the SDK is structured into layers
 ```
 core/ -- Low level packages 
     base/ -- Constants and utilities
-    definitions/ -- Definitions of interfaces required for Platforms, Protocol interfaces and Payload layout structures
+    definitions/ -- Definitions of interfaces for Platforms/Protocols and Payload Layouts
     icons/ -- Logos for chains
 
 connect/ -- Makes use of the interfaces in `definitions` to expose protocols in a platform independent way. 
@@ -26,7 +26,7 @@ platforms/ -- Contains `Platform` and `Protocol` implementations
     solana/ -- Contains Solana `Platform` and `Protocol` implementations
     etc...
 
-sdk/ -- Metapackage that depeneds on the rest of the packages, meant to be a simpler way to install/use. Exports packages in a way that allows for tree shaking unused packages and splitting chunks. 
+sdk/ -- Metapackage that depeneds on the rest of the packages, meant to be a simpler way to install/use.
 
 examples/ -- Examples, also used for README string replace
 ```
@@ -48,6 +48,14 @@ A Protocol (fka `Module`) is a specific application, it provides a set of method
 
 To allow platform agnostic access to Protocols, each Platform that provides the protocol should have its own implementation. 
 
+# Connect package
+
+The `connect` package provides access to all the `Platform` and `Protocol` implementations through their interfaces. 
+
+The `Wormhole` class represents a context to register specific Platforms and set some initial configuration overrides. It provides utility methods to do things like create a `ChainContext` or parse an address.
+
+The `routes` directory contains the logic to make use of the Protocol implementations by composing a route through the use of one or more Protocol interfaces.
+
 # SDK package
 
 The `@wormhole-foundation/sdk` package was created to reduce the confusion reported by devs around what they needed to install and use. 

notes.md

@@ -8,7 +8,7 @@ This document details some things that could be improved about the SDK.
 
 The [token registry](./tokenRegistry/) directory is unused except for importing the tokens from connect, which is no longer necessary.
 
-It is still possible to screw up a transfer (blackhole funds) if the higher level constructs are not used and care is not taken to produce a transfer that is acceptable by the destination chain. I have no suggestions for this that would prevent the platform-specific-oddities from leaking into packages they have no business in besides "better documentation".
+It is still possible to screw up a transfer (blackhole funds) if the higher level constructs (`WormholeTransfer` or `Route`) are not used and care is not taken to produce a transfer that is acceptable by the destination chain. I have no suggestions for this that would prevent the platform-specific-oddities from leaking into packages they have no business in besides "better documentation" or disallow it completely.
 
 Examples: 
 
@@ -27,7 +27,7 @@ Examples:
 
 ### Base
 
-The [tokens](./core/base/src/constants/tokens) consts take up a lot of packed space for marginal benefit. Consider making these a wholly separate package that _can_ be installed and fetched when necessary. 
+The [tokens](./core/base/src/constants/tokens) consts take up a lot of packed space in a widely used package for marginal benefit. Consider making these a wholly separate package that _can_ be installed and fetched when necessary. 
 
 The [nativeChainIds](./core/base/src/constants/nativeChainIds.ts) constants mix different chain id types, causing extra akward type checks to be done. Consider splitting these by platform so that when a `Chain` is passed, the type of chain id can be inferred. Also will help to distinguish between chain id _kinds_ (eip155 vs whatever) since they should be unique at least in that context.
 
@@ -51,12 +51,24 @@ The [protocols](./core/definitions/src/protocols/) should have *standard* fields
 - A disciminator/serde for its VAAs/payloads 
 - Standardized Errors that may be thrown 
 
+Note: it is possible to enforce a namespace adheres to an interface
+```ts
+interface x { doit(): void; }
+interface z { dont(): void; }
+namespace y { export function doit () { return; } }
+// ok
+y satisfies x;
+// not ok, will not compile
+// y satisfies z;
+```
 
-## Connect
 
+## Connect
 
 The [Wormhole](./connect/src/wormhole.ts) class has spotty coverage of util methods. Some of the methods are awkward to have on `Wormhole` like `canonicalAddress` which is already an exported method.  
 
+Getting decent typehints for the [Route](./connect/src/routes/route.ts) implementations has been rough. We should, in the route, provide a typeguard that can be called to narrow the type to itself. This would be helpful to understand the exact types required as input (specific options per route, etc) and what is returned on output (more detailed route specific quote details, etc).
+
 The [Receipt typeguards](./connect/src/types.ts) should also define `hasSourceInitiated`, `hasAttested`, etc for checking if the transfer is _past_ some step.
 
 The [Wormholescan API](./connect/src/whscan-api.ts) should be better documented and possibly autogenerated from the swagger for the api. 
@@ -67,7 +79,7 @@ The classes that implement the [WormholeTransfer](./connect/src/protocols/wormho
 
 Every Protocol implementation defines its own private `createUnsignedTransaction` function, which, kinda sucks. 
 
-The Signer implementations are bad at things like gas estimation or handling errors. It should also provide support for transaction review prior to signing.
+The Signer implementations are bad at things like gas estimation or handling errors. They should also provide support for transaction review prior to signing.
 
 
 ### Evm
@@ -94,5 +106,4 @@ The IBC protocol implementation should probably have just been `Gateway` instead
 
 ### Sui
 
-Disaster show wrt types, a lot of weird type checking to get some deeply nested field in a MoveValue.
-
+Disaster show wrt types, a lot of weird type checking to get some deeply nested field in a MoveValue.