clearnet-sdk

module

v0.5.1 Latest Latest Go to latest Published: Jul 17, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/layer-3/clearnet-sdk

Links

Open Source Insights

README ¶

clearnet-sdk

SDKs and shared protocol libraries for Clearnet integrations.

This repository currently contains:

a Go module, github.com/layer-3/clearnet-sdk, with core protocol types, signing helpers, p2p helpers, and blockchain adapters;
a TypeScript package under sdk/ts, published/imported as @yellow-org/clearnet-sdk;
Docker-backed local devnet tooling for Go and TypeScript integration tests.

The Go SDK is the broader backend-facing SDK. The TypeScript SDK currently focuses on browser and application deposit flows for EVM, Solana, and XRPL.

Repository Layout

Path	Purpose
`pkg/core`	Shared Clearnet data types, operations, transaction references, deposit destinations, and adapter interfaces.
`pkg/blockchain/evm`	Go EVM adapters for vault deposits, withdrawals, signer rotation, registry/faucet/token/fraud interactions, and generated contract bindings.
`pkg/blockchain/sol`	Go Solana custody adapter code, program bindings, deposits, withdrawals, and signer rotation.
`pkg/blockchain/xrpl`	Go XRPL deposits, withdrawals, signer rotation, ticket handling, and payment wire helpers.
`pkg/blockchain/btc`	Go Bitcoin vault deposit, withdrawal, rotation, consolidation, and RPC helpers.
`pkg/decimal`	Decimal amount type used by Go chain adapters.
`pkg/bls`, `pkg/eip712`, `pkg/sign`	Signature and digest helpers.
`pkg/p2p`, `pkg/receipt`, `pkg/log`	Supporting networking, receipt, and logging packages.
`sdk/ts`	TypeScript SDK package, tests, and browser demos. See `sdk/ts/README.md`.
`devnet`	Docker Compose local blockchain devnet and readiness probe. See `devnet/README.md`.

Go SDK

The Go module is rooted at this repository:

go get github.com/layer-3/clearnet-sdk

Common entry points:

pkg/core: chain-neutral interfaces such as VaultDepositor, VaultWithdrawalFinalizer, SignerRotationFinalizer, TxRef, and DepositDestination.
pkg/blockchain/evm: EVM custody vault flows and generated bindings.
pkg/blockchain/sol: Solana custody vault flows.
pkg/blockchain/xrpl: XRPL custody vault flows.
pkg/blockchain/btc: Bitcoin custody vault flows.

Run the Go checks:

make build
make lint
make test

Generated Go files are committed. Regenerate them after changing generation inputs:

make generate

TypeScript SDK

The TypeScript package lives in sdk/ts and is ESM-first.

cd sdk/ts
npm ci
npm run typecheck
npm test
npm run build

Install from an application:

npm install @yellow-org/clearnet-sdk

The package currently exposes vault depositors for:

EVM native ETH and ERC-20 deposits;
Solana native SOL and SPL token deposits;
XRPL native XRP and issued-currency deposits.

Read the package guide and API examples in sdk/ts/README.md.

Browser Demos

The TypeScript package includes local demo apps for manual wallet testing:

npm --prefix sdk/ts run demo:evm
npm --prefix sdk/ts run demo:sol
npm --prefix sdk/ts run demo:xrpl

The demos expect a local or configured chain endpoint, funded wallet accounts, and the chain-specific wallet/browser extension needed by the demo. They are developer aids, not production app templates.

Devnet And Integration Tests

The local devnet runs the chain nodes used by the integration suites:

make devnet
npm --prefix sdk/ts ci
make integration
make devnet-down

Focused targets are available when iterating on one chain:

make devnet-evm
npm --prefix sdk/ts run test:integration:evm

make devnet-sol
npm --prefix sdk/ts run test:integration:sol

make devnet-xrpl
npm --prefix sdk/ts run test:integration:xrpl

make integration runs the Go blockchain integrations and the TypeScript EVM, Solana, and XRPL integration tests. See devnet/README.md for ports, provisioning behavior, and environment overrides.

Development Notes

Use make test for the Go race-enabled test suite.
Use npm --prefix sdk/ts test for TypeScript unit tests.
Use npm --prefix sdk/ts audit --omit=dev --audit-level=moderate when checking runtime dependency advisories for the TypeScript package.
Keep generated files and vendored chain artifacts in sync with their source inputs.
Keep public SDK documentation broad: this repository supports Clearnet integration surfaces, not only custody-specific flows.

License

MIT. See LICENSE.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
devnet
wait command Command wait blocks until every devnet node answers RPC, then exits 0 — so `make devnet` returns only once the infra is ready to drive.	Command wait blocks until every devnet node answers RPC, then exits 0 — so `make devnet` returns only once the infra is ready to drive.
pkg
abiutil Package abiutil provides shared ABI type singletons parsed once at init.	Package abiutil provides shared ABI type singletons parsed once at init.
blockchain
blockchain/btc Package btc implements the Bitcoin custody vault adapter.	Package btc implements the Bitcoin custody vault adapter.
blockchain/evm Package evm implements the chain-agnostic adapter interfaces (see pkg/core) against an EVM chain, one focused type per concern: Depositor and WithdrawalFinalizer (the vault money path), plus RegistryAdapter, TokenAdapter, FraudAdapter, and FaucetAdapter.	Package evm implements the chain-agnostic adapter interfaces (see pkg/core) against an EVM chain, one focused type per concern: Depositor and WithdrawalFinalizer (the vault money path), plus RegistryAdapter, TokenAdapter, FraudAdapter, and FaucetAdapter.
blockchain/evm/abi_refresher command Command abi_refresher regenerates the EVM contract bindings (the `pkg/blockchain/evm/*_abi.go` files) from the vendored ABI + bytecode files under `pkg/blockchain/evm/artifacts/`, using go-ethereum's abigen library directly — no bash, no jq, no external abigen binary, no forge build.	Command abi_refresher regenerates the EVM contract bindings (the `pkg/blockchain/evm/*_abi.go` files) from the vendored ABI + bytecode files under `pkg/blockchain/evm/artifacts/`, using go-ethereum's abigen library directly — no bash, no jq, no external abigen binary, no forge build.
blockchain/sol Package sol implements the chain-agnostic adapter interfaces (see pkg/core) against Solana, over the custody Anchor program.	Package sol implements the chain-agnostic adapter interfaces (see pkg/core) against Solana, over the custody Anchor program.
blockchain/sol/custody
blockchain/sol/idl_refresher command Command idl_refresher regenerates the Solana program bindings (the pkg/blockchain/sol/custody package) from the vendored Anchor IDL using anchor-go's generator library directly — the Solana analog of the EVM abi_refresher (which drives go-ethereum's abigen).	Command idl_refresher regenerates the Solana program bindings (the pkg/blockchain/sol/custody package) from the vendored Anchor IDL using anchor-go's generator library directly — the Solana analog of the EVM abi_refresher (which drives go-ethereum's abigen).
blockchain/xrpl Package xrpl implements the XRP Ledger custody vault via Peersyst/xrpl-go: a depositor that sends tagged Payments, and a multi-sign withdrawal finalizer over a SignerList-configured vault account.	Package xrpl implements the XRP Ledger custody vault via Peersyst/xrpl-go: a depositor that sends tagged Payments, and a multi-sign withdrawal finalizer over a SignerList-configured vault account.
bls
cborx Package cborx provides shared primitive-adapter codecs for the canonical deterministic CBOR (RFC 8949 §4.2) encoding used across the Yellow Network protocol.	Package cborx provides shared primitive-adapter codecs for the canonical deterministic CBOR (RFC 8949 §4.2) encoding used across the Yellow Network protocol.
core This file exists solely to anchor the `go generate` directive that produces pkg/core/cbor_gen.go.	This file exists solely to anchor the `go generate` directive that produces pkg/core/cbor_gen.go.
core/gen command Package main is the cbor-gen driver for pkg/core.	Package main is the cbor-gen driver for pkg/core.
decimal Package decimal — CBOR adapter methods for decimal.Decimal.	Package decimal — CBOR adapter methods for decimal.Decimal.
eip712 Package eip712 provides shared EIP-712 signature verification for both the gateway (HTTP->TCP relay) and the clearnode (TCP command verification).	Package eip712 provides shared EIP-712 signature verification for both the gateway (HTTP->TCP relay) and the clearnode (TCP command verification).
log Package log provides a structured, context-aware logging system with distributed tracing support.	Package log provides a structured, context-aware logging system with distributed tracing support.
p2p/auth Package auth implements the /ynp/auth/1.0.0 libp2p handshake that lets a node prove who it is before a peer accepts its restricted streams (notably the burn/mint receipt protocols).	Package auth implements the /ynp/auth/1.0.0 libp2p handshake that lets a node prove who it is before a peer accepts its restricted streams (notably the burn/mint receipt protocols).
p2p/protocol Package protocol defines the canonical libp2p wire contract: the stream protocol identifiers, the GossipSub topic names, and the framed message structs that travel over them.	Package protocol defines the canonical libp2p wire contract: the stream protocol identifiers, the GossipSub topic names, and the framed message structs that travel over them.
p2p/pubsub Package pubsub is a generic GossipSub publish/subscribe toolset over any cborx-envelope payload: a Publisher[T]/Follower[T] works for any T whose cbor-gen codec lives on *T (e.g.	Package pubsub is a generic GossipSub publish/subscribe toolset over any cborx-envelope payload: a Publisher[T]/Follower[T] works for any T whose cbor-gen codec lives on *T (e.g.
p2p/receipt Package receipt implements the libp2p request/response stream protocols for burn/mint receipt submission.	Package receipt implements the libp2p request/response stream protocols for burn/mint receipt submission.
receipt
sign Package sign abstracts signing identities behind a pluggable, algorithm-aware interface — raw in-memory keys for clients/CLI/tests, KMS backends in production (custody's AWS/GCP signers satisfy this interface unchanged).	Package sign abstracts signing identities behind a pluggable, algorithm-aware interface — raw in-memory keys for clients/CLI/tests, KMS backends in production (custody's AWS/GCP signers satisfy this interface unchanged).