meshjs-cardano

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

meshjs-cardano

When to use

适用场景

Building Cardano dApps with MeshJS (TypeScript/JavaScript)
Integrating CIP-30 wallet connectors
Transaction building in browser or Node.js

使用MeshJS（TypeScript/JavaScript）构建Cardano去中心化应用（dApp）
集成CIP-30钱包连接器
在浏览器或Node.js环境中构建交易

Operating rules (must follow)

操作规则（必须遵守）

Confirm MeshJS version and environment (Next.js, Vite, Node)
Never request seed phrases or private keys
Handle wallet disconnects gracefully
Test on preprod before mainnet

确认MeshJS版本及运行环境（Next.js、Vite、Node）
绝不索要助记词或私钥
优雅处理钱包断开连接的情况
上线主网前先在预生产环境测试

Setup

环境搭建

Installation

安装

bash

npm install @meshsdk/core @meshsdk/react

bash

npm install @meshsdk/core @meshsdk/react

or

yarn add @meshsdk/core @meshsdk/react

undefined

yarn add @meshsdk/core @meshsdk/react

undefined

Provider setup

配置Provider

typescript

import { BlockfrostProvider } from '@meshsdk/core';

const provider = new BlockfrostProvider('<PROJECT_ID>');
// or for preprod:
const provider = new BlockfrostProvider('<PROJECT_ID>', 'preprod');

typescript

import { BlockfrostProvider } from '@meshsdk/core';

const provider = new BlockfrostProvider('<PROJECT_ID>');
// or for preprod:
const provider = new BlockfrostProvider('<PROJECT_ID>', 'preprod');

Wallet connection (React)

钱包连接（React环境）

tsx

import { CardanoWallet, useWallet } from '@meshsdk/react';

function App() {
  const { connected, wallet } = useWallet();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Connected!</p>}
    </div>
  );
}

tsx

import { CardanoWallet, useWallet } from '@meshsdk/react';

function App() {
  const { connected, wallet } = useWallet();

  return (
    <div>
      <CardanoWallet />
      {connected && <p>Connected!</p>}
    </div>
  );
}

Transaction building

交易构建

Simple ADA transfer

简单ADA转账

typescript

import { Transaction } from '@meshsdk/core';

const tx = new Transaction({ initiator: wallet })
  .sendLovelace(
    'addr_test1qz...',
    '5000000'  // 5 ADA
  );

const unsignedTx = await tx.build();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

typescript

import { Transaction } from '@meshsdk/core';

const tx = new Transaction({ initiator: wallet })
  .sendLovelace(
    'addr_test1qz...',
    '5000000'  // 5 ADA
  );

const unsignedTx = await tx.build();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);

With native tokens

包含原生代币的转账

typescript

const tx = new Transaction({ initiator: wallet })
  .sendAssets(
    'addr_test1qz...',
    [
      { unit: 'lovelace', quantity: '2000000' },
      { unit: '<policy_id><asset_name_hex>', quantity: '1' }
    ]
  );

typescript

const tx = new Transaction({ initiator: wallet })
  .sendAssets(
    'addr_test1qz...',
    [
      { unit: 'lovelace', quantity: '2000000' },
      { unit: '<policy_id><asset_name_hex>', quantity: '1' }
    ]
  );

With metadata

包含元数据的转账

typescript

const tx = new Transaction({ initiator: wallet })
  .sendLovelace('addr_test1qz...', '1000000')
  .setMetadata(674, { msg: ['Hello from MeshJS'] });

typescript

const tx = new Transaction({ initiator: wallet })
  .sendLovelace('addr_test1qz...', '1000000')
  .setMetadata(674, { msg: ['Hello from MeshJS'] });

Script interactions

脚本交互

Lock funds at script

将资金锁定到脚本地址

typescript

import { Data } from '@meshsdk/core';

const datum: Data = {
  alternative: 0,
  fields: [wallet.getPaymentAddress()]
};

const tx = new Transaction({ initiator: wallet })
  .sendLovelace(
    {
      address: scriptAddress,
      datum: { inline: datum }
    },
    '5000000'
  );

typescript

import { Data } from '@meshsdk/core';

const datum: Data = {
  alternative: 0,
  fields: [wallet.getPaymentAddress()]
};

const tx = new Transaction({ initiator: wallet })
  .sendLovelace(
    {
      address: scriptAddress,
      datum: { inline: datum }
    },
    '5000000'
  );

Spend from script

从脚本地址提取资金

typescript

const tx = new Transaction({ initiator: wallet })
  .redeemValue({
    value: scriptUtxo,
    script: plutusScript,
    datum: datum,
    redeemer: { data: { alternative: 0, fields: [] } }
  })
  .sendLovelace(recipientAddress, '4500000')
  .setCollateral([collateralUtxo]);

typescript

const tx = new Transaction({ initiator: wallet })
  .redeemValue({
    value: scriptUtxo,
    script: plutusScript,
    datum: datum,
    redeemer: { data: { alternative: 0, fields: [] } }
  })
  .sendLovelace(recipientAddress, '4500000')
  .setCollateral([collateralUtxo]);

Examples

示例

Example: NFT minting

示例：NFT铸造

User request: "Mint an NFT with MeshJS"

Response:

typescript

import { ForgeScript, Transaction } from '@meshsdk/core';

// Create minting script (time-locked)
const { pubKeyHash } = wallet.getPaymentAddress();
const forgingScript = ForgeScript.withOneSignature(pubKeyHash);

const assetMetadata = {
  name: 'My NFT',
  image: 'ipfs://...',
  mediaType: 'image/png'
};

const tx = new Transaction({ initiator: wallet })
  .mintAsset(
    forgingScript,
    {
      assetName: 'MyNFT',
      assetQuantity: '1',
      metadata: assetMetadata,
      label: '721',
      recipient: wallet.getPaymentAddress()
    }
  );

const unsignedTx = await tx.build();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
console.log('Minted:', txHash);

用户需求： "使用MeshJS铸造NFT"

实现代码：

typescript

import { ForgeScript, Transaction } from '@meshsdk/core';

// Create minting script (time-locked)
const { pubKeyHash } = wallet.getPaymentAddress();
const forgingScript = ForgeScript.withOneSignature(pubKeyHash);

const assetMetadata = {
  name: 'My NFT',
  image: 'ipfs://...',
  mediaType: 'image/png'
};

const tx = new Transaction({ initiator: wallet })
  .mintAsset(
    forgingScript,
    {
      assetName: 'MyNFT',
      assetQuantity: '1',
      metadata: assetMetadata,
      label: '721',
      recipient: wallet.getPaymentAddress()
    }
  );

const unsignedTx = await tx.build();
const signedTx = await wallet.signTx(unsignedTx);
const txHash = await wallet.submitTx(signedTx);
console.log('Minted:', txHash);

Example: Query UTxOs

示例：查询UTxO

typescript

import { BlockfrostProvider } from '@meshsdk/core';

const provider = new BlockfrostProvider('<PROJECT_ID>');

// Get UTxOs for address
const utxos = await provider.fetchAddressUTxOs(address);

// Get UTxOs at script address
const scriptUtxos = await provider.fetchAddressUTxOs(scriptAddress);

// Filter by asset
const nftUtxos = utxos.filter(utxo =>
  utxo.output.amount.some(a => a.unit.includes(policyId))
);

typescript

import { BlockfrostProvider } from '@meshsdk/core';

const provider = new BlockfrostProvider('<PROJECT_ID>');

// Get UTxOs for address
const utxos = await provider.fetchAddressUTxOs(address);

// Get UTxOs at script address
const scriptUtxos = await provider.fetchAddressUTxOs(scriptAddress);

// Filter by asset
const nftUtxos = utxos.filter(utxo =>
  utxo.output.amount.some(a => a.unit.includes(policyId))
);

Common patterns

通用开发模式

Error handling

错误处理

typescript

try {
  const txHash = await wallet.submitTx(signedTx);
  console.log('Success:', txHash);
} catch (error) {
  if (error.message.includes('UTxO')) {
    console.log('UTxO issue - refresh and retry');
  } else if (error.message.includes('collateral')) {
    console.log('Need ADA-only UTxO for collateral');
  }
}

typescript

try {
  const txHash = await wallet.submitTx(signedTx);
  console.log('Success:', txHash);
} catch (error) {
  if (error.message.includes('UTxO')) {
    console.log('UTxO issue - refresh and retry');
  } else if (error.message.includes('collateral')) {
    console.log('Need ADA-only UTxO for collateral');
  }
}

Wallet state management

钱包状态管理

typescript

const { connected, connecting, disconnect, wallet, name } = useWallet();

// Check connection before operations
if (!connected) {
  throw new Error('Wallet not connected');
}

// Get network
const network = await wallet.getNetworkId();
// 0 = testnet, 1 = mainnet

typescript

const { connected, connecting, disconnect, wallet, name } = useWallet();

// Check connection before operations
if (!connected) {
  throw new Error('Wallet not connected');
}

// Get network
const network = await wallet.getNetworkId();
// 0 = testnet, 1 = mainnet

Safety / key handling

安全与密钥处理

Never request seed phrases
Validate CIP-30 API availability
Handle disconnects gracefully
Show confirmation before signing

绝不索要助记词
验证CIP-30 API的可用性
优雅处理断开连接的情况
签名前显示确认提示

References

参考资料

```
shared/PRINCIPLES.md
```
MeshJS documentation
CIP-30 Wallet API

```
shared/PRINCIPLES.md
```
MeshJS官方文档
CIP-30钱包API