From d292c1f3e3a430e0ca41c8dcf2a99de43225685a Mon Sep 17 00:00:00 2001 From: Jingles Date: Mon, 14 Sep 2026 09:24:39 +0800 Subject: [PATCH] docs: refresh README to match current packages, fix dead links --- README.md | 214 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 126 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 7d029f574..7b09408eb 100644 --- a/README.md +++ b/README.md @@ -3,157 +3,195 @@ - mesh logo + Mesh SDK logo -

Mesh TypeScript SDK

+

Mesh: the TypeScript SDK for Cardano

-[![Licence](https://img.shields.io/github/license/meshjs/mesh)](https://github.com/meshjs/mesh/blob/master/LICENSE) +[![License](https://img.shields.io/github/license/meshjs/mesh)](https://github.com/MeshJS/mesh/blob/main/LICENSE.md) [![Build](https://github.com/meshjs/mesh/actions/workflows/build.yml/badge.svg)](https://github.com/meshjs/mesh/actions/workflows/build.yml) -[![Package](https://github.com/meshjs/mesh/actions/workflows/publish.yml/badge.svg)](https://github.com/meshjs/mesh/actions/workflows/publish.yml) +[![Publish](https://github.com/meshjs/mesh/actions/workflows/publish.yml/badge.svg)](https://github.com/meshjs/mesh/actions/workflows/publish.yml) +[![npm](https://img.shields.io/npm/v/%40meshsdk%2Fcore)](https://www.npmjs.com/package/@meshsdk/core) +[![npm downloads](https://img.shields.io/npm/dm/%40meshsdk%2Fcore)](https://www.npmjs.com/package/@meshsdk/core) -[![Twitter/X](https://img.shields.io/badge/Follow%20us-@MeshJS-blue?logo=x&style=for-the-badge)](https://x.com/meshsdk) -[![NPM](https://img.shields.io/npm/v/%40meshsdk%2Fcore?style=for-the-badge)](https://www.npmjs.com/package/@meshsdk/core) +[![Discord](https://img.shields.io/badge/Discord-join%20the%20community-5865F2?logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/dH48jH3BKa) +[![Twitter/X](https://img.shields.io/badge/Follow-@meshsdk-blue?logo=x&style=for-the-badge)](https://x.com/meshsdk) -All-in-one TypeScript SDK for UTXO apps +Build Cardano dApps in TypeScript: transactions, wallets, smart contracts and blockchain data in one open-source SDK. + +[Website & live demos](https://meshjs.dev/) · [API docs](https://docs.meshjs.dev/) · [Guides](https://meshjs.dev/guides) · [Examples](https://github.com/MeshJS/examples) · [Discord](https://discord.gg/dH48jH3BKa)
-Mesh is an open-source library designed to make building applications accessible. Whether you're a beginner developer, startup, web3 market leader, or a large enterprise, Mesh makes web3 development easy with reliable, scalable, and well-engineered APIs & developer tools. +Mesh is an open-source TypeScript and JavaScript SDK for building applications on the Cardano blockchain. It handles the hard parts of Cardano development, such as coin selection, fee calculation, CBOR serialization and script evaluation, so you can focus on your app. + +With Mesh you can: + +- **Build transactions** with `MeshTxBuilder`: send ADA and native tokens, mint and burn NFTs, stake, vote in governance, and spend from Plutus and Aiken scripts. +- **Connect wallets** in the browser through CIP-30 (such as Eternl) with `BrowserWallet`, or sign server-side from a mnemonic or private key with `MeshWallet`. +- **Use ready-made smart contracts** for escrow, marketplaces, vesting, swaps and more, each with on-chain code and off-chain TypeScript. +- **Query and submit** through Blockfrost, Koios, Maestro, Ogmios, Yaci and other blockchain providers. +- **Test offline** against a local ledger with the Scalus emulator. -Explore the features on [Mesh Playground](https://meshjs.dev/). +Mesh runs in Node.js, the browser, Next.js and other modern frameworks. -Instant setup a new project with a single command using Mesh CLI and start building: +## Quick start + +Create a new Cardano dApp from a template with the Mesh CLI: ```bash npx meshjs your-app-name ``` -Or install the core package: +Or add Mesh to an existing project: ```bash npm install @meshsdk/core ``` -## What's inside? +### Example: send ADA from a browser wallet + +```ts +import { BlockfrostProvider, BrowserWallet, MeshTxBuilder } from "@meshsdk/core"; + +const provider = new BlockfrostProvider(""); +const wallet = await BrowserWallet.enable("eternl"); + +const txBuilder = new MeshTxBuilder({ fetcher: provider, submitter: provider }); + +const unsignedTx = await txBuilder + .txOut("addr_test1...", [{ unit: "lovelace", quantity: "5000000" }]) + .changeAddress(await wallet.getChangeAddress()) + .selectUtxosFrom(await wallet.getUtxos()) + .complete(); + +const signedTx = await wallet.signTx(unsignedTx); +const txHash = await provider.submitTx(signedTx); +``` + +Try this and many more transactions interactively in the [Mesh playground](https://meshjs.dev/apis/txbuilder). + +## Packages + +This monorepo publishes the core Mesh packages to npm under the `@meshsdk` scope. Most apps only need `@meshsdk/core`, which re-exports transactions, wallets, providers and common utilities. + +| Package | Description | Docs | +| ------- | ----------- | ---- | +| [@meshsdk/core](https://github.com/MeshJS/mesh/tree/main/packages/mesh-core) | The main entry point. Re-exports transactions, wallets, providers and common utilities. | [Playground](https://meshjs.dev/) | +| [@meshsdk/transaction](https://github.com/MeshJS/mesh/tree/main/packages/mesh-transaction) | `MeshTxBuilder` for sending assets, minting tokens and interacting with smart contracts | [Docs](https://docs.meshjs.dev/transactions) · [Playground](https://meshjs.dev/apis/txbuilder) | +| [@meshsdk/wallet](https://github.com/MeshJS/mesh/tree/main/packages/mesh-wallet) | Browser (CIP-30) and headless wallets for managing keys, signing and submitting | [Docs](https://docs.meshjs.dev/wallets) · [Playground](https://meshjs.dev/apis/wallets) | +| [@meshsdk/contract](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract) | Open-source smart contracts with off-chain transaction code | [Docs](https://docs.meshjs.dev/contracts) · [Playground](https://meshjs.dev/smart-contracts) | +| [@meshsdk/common](https://github.com/MeshJS/mesh/tree/main/packages/mesh-common) | Shared constants, types and interfaces used across the SDK | [Docs](https://docs.meshjs.dev/common) | +| [@meshsdk/core-cst](https://github.com/MeshJS/mesh/tree/main/packages/mesh-core-cst) | Serialization and utilities built on cardano-js-sdk and Harmonic Labs libraries | [Docs](https://docs.meshjs.dev/core-cst) | +| [@meshsdk/core-csl](https://github.com/MeshJS/mesh/tree/main/packages/mesh-core-csl) | Serialization and utilities built on Whisky (cardano-serialization-lib) | [Docs](https://docs.meshjs.dev/core-csl) | +| [@meshsdk/scalus-emulator](https://github.com/MeshJS/mesh/tree/main/packages/mesh-scalus-emulator) | Local Cardano ledger emulator built on Scalus, for testing transactions offline | | + +### Packages in other repositories -### Architecture Overview +These `@meshsdk` packages are developed in their own repositories: + +| Package | Description | Repository | +| ------- | ----------- | ---------- | +| @meshsdk/provider | Blockchain data providers (Blockfrost, Koios, Maestro, Ogmios and more) | [MeshJS/providers](https://github.com/MeshJS/providers) | +| @meshsdk/react | React components and hooks for Cardano wallet connection | [MeshJS/react](https://github.com/MeshJS/react) | +| @meshsdk/hydra | Hydra Head protocol client for layer-2 scaling | [MeshJS/hydra](https://github.com/MeshJS/hydra) | +| @meshsdk/midnight-setup | Development setup for Midnight Network dApps | [MeshJS/midnight-setup](https://github.com/MeshJS/midnight-setup) | +| @meshsdk/midnight-contracts-wizard | CLI wizard for new Midnight contract projects | [MeshJS/midnight-contracts-wizard](https://github.com/MeshJS/midnight-contracts-wizard) | + +### Architecture ```mermaid graph TD core["@meshsdk/core"] + common["@meshsdk/common"] core_csl["@meshsdk/core-csl"] core_cst["@meshsdk/core-cst"] provider["@meshsdk/provider"] - react["@meshsdk/react"] transaction["@meshsdk/transaction"] wallet["@meshsdk/wallet"] - sidan_csl["@sidan-lab/*"] + contract["@meshsdk/contract"] + emulator["@meshsdk/scalus-emulator"] + whisky["@sidan-lab/whisky-js"] cardano_sdk["@cardano-sdk/*"] harmoniclabs["@harmoniclabs/*"] - core --> core_csl - core --> core_cst + contract --> core core --> provider - core --> react core --> transaction core --> wallet - provider --> core_cst - - react --> transaction - react --> wallet - transaction --> core_csl + core --> core_cst + wallet --> transaction transaction --> core_cst + emulator --> core_cst - subgraph serializer - core_csl --> sidan_csl + subgraph serializers + core_csl --> whisky core_cst --> cardano_sdk core_cst --> harmoniclabs end + core_cst --> common + core_csl --> common + click core_csl "https://docs.meshjs.dev/core-csl" _parent click core_cst "https://docs.meshjs.dev/core-cst" _parent - click provider "https://docs.meshjs.dev/providers" _parent - click react "https://meshjs.dev/react" _parent + click provider "https://github.com/MeshJS/providers" _parent click transaction "https://docs.meshjs.dev/transactions" _parent click wallet "https://docs.meshjs.dev/wallets" _parent + click contract "https://docs.meshjs.dev/contracts" _parent ``` -### Packages - -A collection of packages that provide different functionalities to interact with the Cardano blockchain. - -| | Description | Docs | Playground | -| ----------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| [@meshsdk/common](https://github.com/MeshJS/mesh/tree/main/packages/mesh-common) | Contains constants, types and interfaces used across the SDK and different serialization libraries | [:page_facing_up:](https://docs.meshjs.dev/common) | | -| [@meshsdk/contract](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract) | A collection of smart contracts and its transactions | [:page_facing_up:](https://docs.meshjs.dev/contracts) | [:shipit:](https://meshjs.dev/smart-contracts) | -| [@meshsdk/core](https://github.com/MeshJS/mesh/tree/main/packages/mesh-core) | Exports all the functionalities including wallets, transactions, and providers | | [:shipit:](https://meshjs.dev/) | -| [@meshsdk/core-csl](https://github.com/MeshJS/mesh/tree/main/packages/mesh-core-csl) | Types and utilities functions between Mesh and cardano-serialization-lib | [:page_facing_up:](https://docs.meshjs.dev/core-csl) | | -| [@meshsdk/core-cst](https://github.com/MeshJS/mesh/tree/main/packages/mesh-core-cst) | Types and utilities functions between Mesh and cardano-js-sdk | [:page_facing_up:](https://docs.meshjs.dev/core-cst) | | -| [@meshsdk/provider](https://github.com/MeshJS/mesh/tree/main/packages/mesh-provider) | Blockchain data providers | [:page_facing_up:](https://docs.meshjs.dev/providers) | [:shipit:](https://meshjs.dev/providers) | -| [@meshsdk/react](https://github.com/MeshJS/mesh/tree/main/packages/mesh-react) | React component library | | [:shipit:](https://meshjs.dev/react) | -| [@meshsdk/transaction](https://github.com/MeshJS/mesh/tree/main/packages/mesh-transaction) | Transactions to send assets, mint tokens, and interact with smart contracts | [:page_facing_up:](https://docs.meshjs.dev/transactions) | [:shipit:](https://meshjs.dev/apis/transaction) | -| [@meshsdk/wallet](https://github.com/MeshJS/mesh/tree/main/packages/mesh-wallet) | Wallets to manage assets and interact with the blockchain | [:page_facing_up:](https://docs.meshjs.dev/wallets) | [:shipit:](https://meshjs.dev/apis/wallets) | -| [@meshsdk/midnight-setup](https://github.com/MeshJS/mesh/tree/main/packages/midnight-setup) | Complete development setup for building Midnight Network dApps | [:page_facing_up:](https://midnight.meshjs.dev/en/packages/midnight_setup) | [:shipit:](https://github.com/MeshJS/midnight-setup) | -| [@meshsdk/midnight-contracts-wizard](https://github.com/MeshJS/mesh/tree/main/packages/midnight-contracts-wizard) | CLI wizard to create new Midnight contracts projects with pre-built smart contracts | [:page_facing_up:](https://midnight.meshjs.dev/en/packages/midnight_contracts_wizard) | [:shipit:](https://www.npmjs.com/package/@meshsdk/midnight-contracts-wizard) | - -### Apps - -Frontend documentation and live demos for Mesh SDK. +## Cardano smart contracts library -| | Description | Website | -| --------------------------------------------------------------------------- | ---------------------------- | ------------------------------------ | -| [apps/docs](https://github.com/MeshJS/mesh/tree/main/apps/docs) | Mesh technical docs | [:shipit:](https://docs.meshjs.dev/) | -| [apps/playground](https://github.com/MeshJS/mesh/tree/main/apps/playground) | Mesh homepage and live demos | [:shipit:](https://meshjs.dev/) | +`@meshsdk/contract` includes open-source Cardano smart contracts, each with on-chain Aiken code, off-chain TypeScript, documentation and a live demo. -### Mesh Smart Contracts Library +| Contract | What it does | Links | +| -------- | ------------ | ----- | +| Content Ownership | A registry where users create content that is recorded on-chain | [Demo](https://meshjs.dev/smart-contracts/content-ownership) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/content-ownership) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshContentOwnershipContract) | +| Escrow | Holds assets between two parties until both agree to complete the exchange | [Demo](https://meshjs.dev/smart-contracts/escrow) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/escrow) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshEscrowContract) | +| Giftcard | Locks assets behind a newly minted gift card token; redeeming burns the token and releases the assets | [Demo](https://meshjs.dev/smart-contracts/giftcard) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/giftcard) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshGiftcardContract) | +| Hello World | A simple lock-and-unlock contract to learn end-to-end validation and transaction building | [Demo](https://meshjs.dev/smart-contracts/hello-world) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/hello-world) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshHelloWorldContract) | +| Marketplace | An NFT marketplace where anyone can list, buy and sell native assets | [Demo](https://meshjs.dev/smart-contracts/marketplace) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/marketplace) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshMarketplaceContract) | +| NFT Minting Machine | Mints NFTs with an index that increments by one for each new token | [Demo](https://meshjs.dev/smart-contracts/plutus-nft) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/plutus-nft) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshPlutusNFTContract) | +| Payment Splitter | Splits incoming payments among a group of addresses | [Demo](https://meshjs.dev/smart-contracts/payment-splitter) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/payment-splitter) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshPaymentSplitterContract) | +| Swap | Exchanges assets between two parties | [Demo](https://meshjs.dev/smart-contracts/swap) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/swap) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshSwapContract) | +| Vesting | Locks tokens until a set time, after which the beneficiary can withdraw them | [Demo](https://meshjs.dev/smart-contracts/vesting) · [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/vesting) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshVestingContract) | +| Asteria _(work in progress)_ | A bot challenge where ships race across a 2D grid to showcase the eUTxO model | [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/asteria) | +| Royalties _(work in progress)_ | CIP-102 royalties for NFTs | [Source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/royalties) · [Docs](https://docs.meshjs.dev/contracts/classes/MeshRoyaltiesContract) | -Here's a list of open-source smart contracts, complete with documentation, live demos, and end-to-end source code. +## Developing Mesh -| Contract | Description | Links | -| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Content Ownership | Create a content registry and users can create content that is stored in the registry | [[demo](https://meshjs.dev/smart-contracts/content-ownership)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/content-ownership)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshContentOwnershipContract)] | -| Escrow | Facilitates the secure exchange of assets between two parties by acting as a trusted intermediary that holds the assets until the conditions of the agreement are met | [[demo](https://meshjs.dev/smart-contracts/escrow)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/escrow)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshEscrowContract)] | -| Giftcard | Allows users to create a transactions to lock assets into the smart contract, which can be redeemed by any user | [[demo](https://meshjs.dev/smart-contracts/giftcard)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/giftcard)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshGiftcardContract)] | -| Hello World | A simple lock-and-unlock assets contract, providing a hands-on introduction to end-to-end smart contract validation and transaction building | [[demo](https://meshjs.dev/smart-contracts/hello-world)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/hello-world)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshHelloWorldContract)] | -| Marketplace | Allows anyone to buy and sell native assets such as NFTs | [[demo](https://meshjs.dev/smart-contracts/marketplace)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/marketplace)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshMarketplaceContract)] | -| NFT Minting Machine | Mint NFTs with an automatically incremented index, which increases by one for each newly minted NFT | [[demo](https://meshjs.dev/smart-contracts/plutus-nft)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/plutus-nft)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshPlutusNFTContract)] | -| Payment Splitter | Allows users to split incoming payments among a group of accounts | [[demo](https://meshjs.dev/smart-contracts/payment-splitter)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/payment-splitter)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshPaymentSplitterContract)] | -| Swap | Facilitates the exchange of assets between two parties | [[demo](https://meshjs.dev/smart-contracts/swap)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/swap)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshSwapContract)] | -| Vesting | Allows users to lock tokens for a period of time and withdraw the funds after the lockup period | [[demo](https://meshjs.dev/smart-contracts/vesting)] [[source](https://github.com/MeshJS/mesh/tree/main/packages/mesh-contract/src/vesting)] [[docs](https://docs.meshjs.dev/contracts/classes/MeshVestingContract)] | +Mesh is a Turborepo monorepo using npm workspaces. You need Node.js 18 or later. -## Usage - -### Install - -To install all dependencies, run the following command: - -``` +```bash +git clone https://github.com/MeshJS/mesh.git +cd mesh npm install -``` - -### Build - -To build all apps and packages, run the following command: - -``` npm run build ``` -### Run +| Command | What it does | +| ------- | ------------ | +| `npm run build` | Build all packages | +| `npm run dev` | Build packages in watch mode | +| `npm test` | Run the test suites | +| `npm run lint` | Lint all packages | +| `npm run format` | Check formatting with Prettier (`format:fix` to apply) | -To run all apps and packages, run the following command: +## Contributing -``` -npm run dev -``` +Contributions of all kinds are welcome: bug fixes, new features, documentation, tests, and help triaging issues and pull requests. -## Contributing +- Read the [contributing guide](https://github.com/MeshJS/mesh/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/MeshJS/mesh/blob/main/CODE_OF_CONDUCT.md). +- See the [developer docs](https://github.com/MeshJS/mesh/tree/main/docs) for coding and pull request guidelines. +- Report bugs and request features in [GitHub issues](https://github.com/MeshJS/mesh/issues), or ask questions on [Discord](https://discord.gg/dH48jH3BKa). + +Using an AI coding assistant? [MeshJS/skills](https://github.com/MeshJS/skills) gives Claude Code, Cursor, Codex and other tools deep knowledge of the Mesh SDK. -Mesh SDK project welcomes all constructive contributions. Contributions take many forms, from code for bug fixes and enhancements, to additions and fixes to documentation, additional tests, triaging incoming pull requests and issues, and more! +## License -Check out the [contributing guide](https://github.com/MeshJS/mesh/blob/main/CONTRIBUTING.md). +Mesh is released under the [Apache 2.0 License](https://github.com/MeshJS/mesh/blob/main/LICENSE.md). -![Alt](https://repobeats.axiom.co/api/embed/a55b792080ada8db32fb84c10addc7b4afab7679.svg "Repobeats analytics image") +![Repobeats analytics](https://repobeats.axiom.co/api/embed/a55b792080ada8db32fb84c10addc7b4afab7679.svg "Repobeats analytics image")