Contribute a Module to WDK

Read this page before you write code. It covers the CLI, the contract, what we check, and how to request a review.

Start With the CLI

Every module starts from create-wdk-module. It generates the package name, initial version, types, Bare entry, and CI workflows.

npx @tetherto/create-wdk-module@latest

Enter your module type, name, and npm scope, then keep what it generates. The generated tests are test.todo placeholders, so a passing npm test means nothing until you replace them.

Where Your Module Sits

An application registers your module with WDK Core. Your module extends the base classes in @tetherto/wdk-wallet and talks to your chain or provider.

Implement the Contract

The latest @tetherto/wdk-wallet release is the contract. Its source defines every method, type, and documented error, so this page does not repeat them. If a reference implementation disagrees with the interface, the interface wins. JavaScript and TypeScript are both fine, as long as you publish executable JavaScript and type declarations.

Rules the Types Can't Express

Type checking passes without any of these, so test them yourself.

Every module

• Run on Bare. WDK applications can run wallet operations in a Bare thread, so your Bare entry must work there, dependencies included. The CLI generates the entry, and wdk-wallet-btc shows a released one. If you are blocked, send us the failing dependency, a reproducer, and the affected operations. Only an approved waiver lifts this rule, and it goes in your README.
• Resolve one copy of @tetherto/wdk-wallet. Core recognizes protocols with instanceof. With a second copy, registerProtocol() ignores your module without an error, and getSwapProtocol() throws later. Keep the version range the CLI generates.
• Keep failures distinct. Invalid input, unsupported operations, missing configuration, and provider failures are never an empty or successful result. Reuse WDK errors and protocol errors first, extend WdkError for your own, and mark each one with @throws. Export the errors you throw from your package root, or document their import path.
• Never lose a transaction. Return transaction identifiers and partial-execution details in results or errors so callers can recover. Keep a failed submission distinct from an unknown broadcast outcome.
• Add, don't redefine. Never change the meaning or return shape of an inherited method.
• Leave secrets and logs to the host. No keys or credentials in source, fixtures, logs, or examples. No console.log, because hosts log through Core middleware. Disclose provider requests and telemetry.

Protocol modules

• Sign with the host's account. Never ask for a seed phrase or create a second signer. Use chain module types where they specialize the base ones: EVM calldata goes through EvmTransaction.
• Report status honestly. An unrecognized status in a valid response maps to pending for swidge and SDA, or in_progress for fiat. Invalid identifiers, missing records, and failed requests are errors.
• Honor fee caps. Throw MaximumFeeExceededError when swapMaxFee or bridgeMaxFee is exceeded.

Wallet modules

• Override both account factories. A variant that changes the account class overrides getAccount() and getAccountByPath(). Name it wdk-wallet-<chain>-<variant>.
• Clear your own state. Extra keys or sessions are yours to clear in dispose(), after super.dispose().

Pre-Review Checklist

Copy this list into your review request and tick only what you actually ran. Explain any box you leave empty. The review skills run in your coding agent:

npx skills add tetherto/wdk-agent-skills

Package

• The name from create-wdk-module is unchanged and free on npm.
• npm run lint passes, and npm run build:types leaves types/ unchanged.
• Every direct dependency is used, and nothing needed at runtime sits in devDependencies.
• The npm pack output installs in a new project with @tetherto/wdk, and npm ls @tetherto/wdk-wallet shows one version.

Behavior

• npm test passes with no test.todo left, and covers every documented error.
• The main flow runs end to end through Core and a real WDK wallet package, with no mocks or sender stubs. Where a transaction applies, the request lists its network and hash, or the fork block height.
• The same flow runs from the packed Bare entry (how to run a test under Bare), or an approved waiver is in the README.
• If you hold extra state, disposal is tested through both the account and the manager.
• wdk-review-jsdocs, wdk-review-dts, and wdk-review-tests have run, with findings fixed or listed.

Documentation

• The README has install steps, a runnable example, configuration, supported chains and operations, errors with caller actions, fees, known limitations, supported WDK versions, migration steps for breaking changes, and support and security contacts.
• Bundler, Bare, credential, and real-funds caveats sit next to the run commands, not only in example comments.
• The repository holds no real credentials, and .env.example lists every variable that tests and examples read.
• Examples use Tether assets or neutral placeholders.

Request a Review

Send the repository, a reviewable PR, the full commit SHA, the package name and version, your checklist, and your test results through the WDK Tech Contributors track. If we request changes, fix them and run the checklist again.

We don't test every network, asset, or edge case. Approval applies to one commit, the way an audit does. Anything you change afterwards needs a new review before you describe it as approved. We may flag obvious defects, but approval is not an audit of the right-hand column.

After approval, prepare a docs PR on wdk-docs and keep it in draft. Publish to npm under your scope, confirm the version matches the approved commit, then mark the PR ready for review.

CLI Reference

Need Help?