more

Author: barnjamin

DESIGN.md

@@ -2,11 +2,9 @@
 
 ## Structure
 
-A primary goal for the SDK was to provide modular and specific access to the protocols build on Wormhole. 
-
+A primary goal for the SDK is to provide modular and specific access to the protocols build on Wormhole. 
 
 To address this goal, the SDK is structured into layers
-
 ```
 core/ -- Low level packages 
     base/ -- Constants and utilities
@@ -33,21 +31,34 @@ examples/ -- Examples, also used for README string replace
 
 # Interfaces
 
+Interfaces defined in `core/definitions` are implemented for each platform on which they are supported. 
+
 ## Platform Interfaces 
 
 Several interfaces should be available for each platform supported.
 
 - A `Platform` is a blockchain runtime, often shared across a number of chains (e.g. `Evm` platform for `Ethereum`, `Bsc`, `Polygon`, etc ...). 
+
 - A `Chain` is a specific blockchain, potentially with overrides for slight differences in the platform implementation. 
-- A `Signer` is an interface that provides a callback to `sign` or `signAndSend` one or more transaction objects. 
+
 - An `Address` provides parsing/formatting/conversion for platform specific addresses. 
 
+- A `Signer` is an interface that provides a callback to `sign` or `signAndSend` one or more transaction objects. 
+
+    > The Signer interface is intended to be flexible enough to allow devs to provide their own implementation with more specific transaction creation/configuration/submission logic than what could be covered in the default provided signers. It also allows for the creation of Signers that wrap hardware wallets or web wallets.
+
 ## Protocol Interfaces
 
 A Protocol (fka `Module`) is a specific application, it provides a set of methods that can be called to accomplish some action (e.g. `TokenBridge` allows `transfer`/`redeem`/`getWrappedAsset`, etc...)
 
 To allow platform agnostic access to Protocols, each Platform that provides the protocol should have its own implementation. 
 
+# Platform packages
+
+Each platform has implementations of the relevant interfaces from `core/definitions` as well as implementations for each protocol supported on that platform.
+
+The platform package should be the only one that depends on packages for that platform (eg ethersv6 for evm).
+
 # Connect package
 
 The `connect` package provides access to all the `Platform` and `Protocol` implementations through their interfaces. 
@@ -64,5 +75,4 @@ Because this project has strict separation of platform implementation packages,
 
 This package specifies _all_ platforms and protocols as dependencies which increases installed size but provides provides conditional exports for each `Platform` to allow for a smaller bundle size.
 
-Each platform has a `PlatformDefiniton` containing the `Platform` specific implementations that can be imported directly or through the `PlatformLoader` which ensures the protocols are registered as well.
-
+Each platform has a `PlatformDefiniton` containing the `Platform` specific implementations that can be imported directly or through the `PlatformLoader` which ensures the protocols are registered as well.

notes.md

@@ -35,13 +35,16 @@ The [nativeChainIds](./core/base/src/constants/nativeChainIds.ts) constants mix
 
 The [Network](./core/base/src/constants/networks.ts) value "Devnet" is confusing to folks coming from Solana since it refers to some ci or local network configuration profile and what they actually want is "Testnet". 
 
-The network breakdown might serve better as a named configuration profile instead where the dev would not have to, for example, map the name "Ethereum" to (Mainnet->Ethereum, Testnet->Sepolia), rather, that would be part of the configuration profile definition. Possibly defined as overrides from the defaults of "Mainnet"|"Testnet"|"Devnet".
+The network breakdown might serve better as a named configuration profile instead, where the dev would not have to, for example, map the name "Ethereum" to (Mainnet->Ethereum, Testnet->Sepolia), rather, that would be part of the configuration profile definition. Possibly defined as overrides from the defaults of "Mainnet"|"Testnet"|"Devnet".
 
 This would constitute a large change since the Network type is a generic parameter for many other types.
 
+The [layouts](./core/base/src/utils/layout/index.ts) could be broken out into their own package for more generic uses outside the context of the wormhole sdk.
+
 ### Definitions
 
-The [layouts](./core/definitions/src/protocols/tokenBridge/tokenBridgeLayout.ts) for the protocols are very difficult to read/comprehend from just source. We could have some way to write out the full object produced so that the fields it contains are easier to read.
+
+The [layout definitions](./core/definitions/src/protocols/tokenBridge/tokenBridgeLayout.ts) for the protocols are very difficult to read/comprehend from just source. We could have some way to write out the full object produced so that the fields it contains are easier to read.
 
 The [Attestation/AttestationId](./core/definitions/src/attestation.ts) could be registered along with the protocol instead of having a hardcoded switch case.  The current definition makes it very awkward to use for anything outside this repo, but since its used in the Routes, external "plugins" need to have _something_. This forces the Attestation type to be a punted `VAA<"Uint8Array">`