From 4751cab831f3fe3c69667c6952ea22f39e05b8d4 Mon Sep 17 00:00:00 2001 From: tyler-nguyen-4 Date: Mon, 30 Jun 2025 10:47:11 +0700 Subject: [PATCH 1/3] feat: add cardano dapp connector documentation --- developers/mobile-cardano.md | 213 +++++++++++++++++++++++++++++++++++ developers/mobile-wallet.md | 1 + 2 files changed, 214 insertions(+) create mode 100644 developers/mobile-cardano.md diff --git a/developers/mobile-cardano.md b/developers/mobile-cardano.md new file mode 100644 index 000000000..e6d0e4bc2 --- /dev/null +++ b/developers/mobile-cardano.md @@ -0,0 +1,213 @@ +# Mobile Wallet Cardano Integration + +This document provides details on integrating Cardano with the mobile wallet application. The integration supports various functionalities such as retrieving account information, signing transactions, and signing data based on the [CIP-30 specification](https://cips.cardano.org/cip/CIP-30). + +## Installation & Setup + +### Install dependencies + +The document uses the appkit of Reown to deploy. Please refer to the documentation at [here](https://docs.reown.io/appkit/overview). + +```bash +npm install @reown/appkit +``` + +### Initialize the appkit + +```javascript +import { createAppKit } from '@reown/appkit/core' +import { defineChain } from '@reown/appkit/networks' + +const cardano = defineChain({ + id: 'cardano-mainnet', + caipNetworkId: 'cip34:1-764824073', + chainNamespace: 'cip34', + name: 'Cardano Mainnet', + nativeCurrency: { + name: 'Cardano', + symbol: 'ADA', + decimals: 6 + }, + rpcUrls: { + default: { http: ['https://rpc.walletconnect.org/v1'] } + }, + blockExplorerUrls: { + default: { name: 'Cardanoscan', url: 'https://cardanoscan.io' } + } +}) + +// Instantiate AppKit +const modal = createAppKit({ + adapters: [], + networks: [cardano], + projectId, + themeMode: 'light', + features: { + analytics: true + }, + metadata: { + name: 'AppKit HTML Example', + description: 'AppKit HTML Example', + url: 'https://reown.com/appkit', + icons: [] + } +}) + +// Subscribe to state changes +modal.subscribeProviders(state => { + provider = state['cip34'] +}) +``` + +## Methods + +### cardano_getBalance +This method returns the total balance available of the wallet + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_getBalance', + params: {} +}); +``` + +#### Returns +- The total balance as CBOR-encoded value. + +### cardano_getNetworkId +This method returns the network ID of the currently connected network. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_getNetworkId', + params: {} +}); +``` + +#### Returns +- Network identifier (0 for testnet, 1 for mainnet). + +### cardano_getUtxos +This method returns a list of all UTXOs (unspent transaction outputs) controlled by the wallet. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_getUtxos', + params: [ + `cbor_encoded` + { page: 0, limit: 50 } // Optional: pagination + ] +}); +``` + +#### Parameters +- `amount`: (Optional) Minimum ADA and token value to filter UTXO. +- `paginate`: (Optional) Pagination object with page and limit. + +#### Returns +- Array of CBOR-encoded TransactionUnspentOutput objects or null. + +### cardano_getCollateral +This method returns UTXOs that are suitable for use as collateral inputs for transactions with Plutus script witnesses. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_getCollateral', + params: {} +}); +``` + +#### Returns +- Array of CBOR-encoded TransactionUnspentOutput objects suitable for collateral. + +### cardano_getUsedAddresses +This method returns a list of all used addresses controlled by the wallet. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_getUsedAddresses', + params: [ + { page: 0, limit: 50 } // Optional: pagination + ] +}); +``` + +#### Parameters +- `paginate`: (Optional) Pagination object with page and limit. + +#### Returns +- Array of hex-encoded address bytes. + +### cardano_getUnusedAddresses +This method returns a list of unused addresses controlled by the wallet. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_getUnusedAddresses', + params: [] +}); +``` + +#### Returns +- Array of hex-encoded unused address bytes. + +### cardano_getChangeAddress +This method returns an address owned by the wallet that should be used as a change address. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_getChangeAddress', + params: [] +}); +``` + +#### Returns +- Hex-encoded change address bytes. + +### cardano_signTx +This method requests that a user sign the unsigned portions of the supplied transaction. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_signTx', + params: [ + 'cbor_encoded_transaction', // CBOR-encoded transaction + false // Optional: whether to allow partial signing + ] +}); +``` + +#### Parameters +- `tx`: CBOR-encoded transaction to be signed. +- `partialSign`: (Optional) Boolean indicating if partial signing is allowed. + +#### Returns +- CBOR-encoded transaction witness set containing the signatures. + +### cardano_submitTx +This method requests that a transaction be submitted to the Cardano network. + +#### Example +```javascript +const result = await provider.request({ + method: 'cardano_submitTx', + params: [ + 'cbor_encoded_signed_transaction' // CBOR-encoded signed transaction + ]}); +``` + +#### Parameters +- `tx`: CBOR-encoded signed transaction to be submitted. + +#### Returns +- Transaction hash (32-byte hex string) for tracking the transaction. + +For more details, refer to the [CIP-30 Cardano dApp-Wallet Web Bridge](https://cips.cardano.org/cip/CIP-30). diff --git a/developers/mobile-wallet.md b/developers/mobile-wallet.md index 44e164ce1..90b419c19 100644 --- a/developers/mobile-wallet.md +++ b/developers/mobile-wallet.md @@ -26,6 +26,7 @@ Reown (aka WalletConnect) is an open protocol for connecting desktop DApps to mo | Solana | ✅ | ✅ | | Cosmos | ✅ | ✅ | | Tron | ✅ | ✅ | +| Cardano | ✅ | ✅ | ## Testing Wallet From b5b0595b469043bcef450e7b6a67e76931662845 Mon Sep 17 00:00:00 2001 From: tyler-nguyen-4 Date: Mon, 30 Jun 2025 11:14:29 +0700 Subject: [PATCH 2/3] chore: update link path --- .vitepress/config.ts | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 858524937..6c0b0bade 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -413,6 +413,10 @@ export default { text: 'Tron', link: '/developers/mobile-tron', }, + { + text: 'Cardano', + link: '/developers/mobile-cardano', + }, ], }, { From 0da8c3a3f211f2cfb2bc89e35a64a0cafdac0aa8 Mon Sep 17 00:00:00 2001 From: sotatek-tyler-nguyen4 <166351995+sotatek-tyler-nguyen4@users.noreply.github.com> Date: Mon, 30 Jun 2025 18:09:06 +0700 Subject: [PATCH 3/3] feat: update developer document with cardano integration & social links (#94) * feat: update developer document with cardano integration & social links * fix: update social links * fix: cip 30 response --------- Co-authored-by: tyler-nguyen-4 --- .vitepress/config.ts | 50 +++++---- CONTRIBUTING.md | 6 +- developers/extension-cardano.md | 178 ++++++++++++++++++++++++++++++++ developers/extension-wallet.md | 3 + developers/introduction.md | 2 +- 5 files changed, 214 insertions(+), 25 deletions(-) create mode 100644 developers/extension-cardano.md diff --git a/.vitepress/config.ts b/.vitepress/config.ts index 6c0b0bade..5253fd1b1 100644 --- a/.vitepress/config.ts +++ b/.vitepress/config.ts @@ -338,6 +338,10 @@ export default { text: 'Bitcoin Cash', link: '/developers/extension-bitcoin-cash', }, + { + text: 'Cardano', + link: '/developers/extension-cardano', + }, { text: 'Cosmos', link: '/developers/extension-cosmos', @@ -390,32 +394,36 @@ export default { link: '/developers/mobile-bitcoin', }, { - text: 'Dogecoin', - link: '/developers/mobile-dogecoin', + text: 'Bitcoin Cash', + link: '/developers/mobile-bitcoin-cash', }, { - text: 'Litecoin', - link: '/developers/mobile-litecoin', + text: 'Cardano', + link: '/developers/mobile-cardano', }, { - text: 'Solana', - link: '/developers/mobile-solana', + text: 'Cosmos', + link: '/developers/mobile-cosmos', + }, + { + text: 'Dogecoin', + link: '/developers/mobile-dogecoin', }, { text: "Ethereum (EVM's)", link: '/developers/mobile-ethereum', }, { - text: 'Cosmos', - link: '/developers/mobile-cosmos', + text: 'Litecoin', + link: '/developers/mobile-litecoin', }, { - text: 'Tron', - link: '/developers/mobile-tron', + text: 'Solana', + link: '/developers/mobile-solana', }, { - text: 'Cardano', - link: '/developers/mobile-cardano', + text: 'Tron', + link: '/developers/mobile-tron', }, ], }, @@ -714,14 +722,14 @@ export default { text: '🔖 Community', collapsed: true, items: [ - { text: '🔹 X', link: 'https://x.com/xdefi_wallet' }, - { text: '🔹 Discord', link: 'https://discord.gg/xdefi' }, - { text: '🔹 Telegram', link: 'https://t.me/xdefi_announcements' }, + { text: '🔹 X', link: 'https://x.com/ctrl_wallet' }, + { text: '🔹 Discord', link: 'https://discord.gg/ctrlwallet' }, + { text: '🔹 Telegram', link: 'https://t.me/ctrl_wallet' }, { text: '🔹 GitHub', link: 'https://github.com/XDeFi-tech' }, - { text: '🔹 Blog', link: 'https://xdefi.io/blog' }, + { text: '🔹 Blog', link: 'https://ctrl.xyz/news' }, { - text: '🔹 $XDEFI on Coingecko', - link: 'https://www.coingecko.com/en/coins/xdefi', + text: '🔹 $CTRL on Coingecko', + link: 'https://www.coingecko.com/en/coins/ctrl-wallet', }, ], }, @@ -734,9 +742,9 @@ export default { socialLinks: [ { icon: 'github', link: 'https://github.com/XDeFi-tech' }, - { icon: 'x', link: 'https://x.com/xdefi_wallet' }, - { icon: 'discord', link: 'https://discord.com/invite/xdefi' }, - { icon: { svg: telegramSVG }, link: 'https://t.me/xdefi_announcements' }, + { icon: 'x', link: 'https://x.com/ctrl_wallet' }, + { icon: 'discord', link: 'https://discord.gg/ctrlwallet' }, + { icon: { svg: telegramSVG }, link: 'https://t.me/ctrl_wallet' }, ], editLink: { diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 04c8bde29..fcf7afaa7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,7 +10,7 @@ Following these guidelines helps to communicate that you respect the time of the Ctrl (fka XDEFI) Technologies is a community-driven project, and we welcome contributions from the community. Whether you're fixing a typo, adding a new feature, or changing the documentation, we'd love to have your contributions. -Please, don't use the issue tracker for personal support requests. Instead, use the [Ctrl Discord](https://discord.gg/xdefi) for support. +Please, don't use the issue tracker for personal support requests. Instead, use the [Ctrl Discord](https://discord.gg/ctrlwallet) for support. ## Ground Rules @@ -60,9 +60,9 @@ When suggesting a feature, please provide as much detail as possible. Explain wh ## Community -Discussions about the documentation take place on the [Ctrl Discord](https://discord.gg/xdefi). +Discussions about the documentation take place on the [Ctrl Discord](https://discord.gg/ctrlwallet). -We also available on [X](https://x.com/xdefi_wallet) and [Telegram](https://t.me/xdefi_announcements). +We also available on [X](https://x.com/ctrl_wallet) and [Telegram](https://t.me/ctrl_wallet). ## Code of Conduct diff --git a/developers/extension-cardano.md b/developers/extension-cardano.md new file mode 100644 index 000000000..724ff2f5b --- /dev/null +++ b/developers/extension-cardano.md @@ -0,0 +1,178 @@ +# Extension Wallet Cardano Integration + +Develop Cardano based dApps + +It injects a CIP-30 compatible provider in `window.cardano.ctrl` and follows the [CIP-30 specification](https://cips.cardano.org/cip/CIP-30) for dApp-wallet communication. + +### Introduction + +- [CIP-30: Cardano dApp-Wallet Web Bridge documentation](https://cips.cardano.org/cip/CIP-30) + +### Example dApp + +- [Cardano Web3 example](https://github.com/XDeFi-tech/examples-dapps-sdk/tree/main/cardano) + +### How to detect XDEFI's Cardano provider + +As the official [CIP-30 guide](https://cips.cardano.org/cip/CIP-30) mentioned: + +```javascript +window.onload = async () => { + if (!window.cardano?.ctrl) { + alert("Please install XDEFI extension"); + } else { + const cardanoWallet = window.cardano.ctrl; + + // Enabling before using the Cardano wallet is recommended. + // This method will ask the user whether to allow access if they haven't visited this website. + // Also, it will request that the user unlock the wallet if the wallet is locked. + const api = await cardanoWallet.enable(); + + // You can get the balance using getBalance method + const balance = await api.getBalance(); + + // Get all used addresses + const usedAddresses = await api.getUsedAddresses(); + + console.log('Wallet connected successfully'); + } +}; +``` + +### Integrate Cardano dApps with Ctrl (fka XDEFI) + +#### `window.cardano.ctrl` + +Ctrl (fka XDEFI) injects `window.cardano.ctrl` as a [CIP-30](https://cips.cardano.org/cip/CIP-30) compatible provider; + +As a dApp developer, you can check if `window.cardano && window.cardano.ctrl` is defined. + +If it is, XDEFI is injected and supports Cardano. + +You can use it with regular Cardano libraries such as cardano-serialization-lib. + +**Basic Connection Example** + +```javascript +// Check if Ctrl (fka XDEFI) is available +if (window.cardano && window.cardano.ctrl) { + const cardanoWallet = window.cardano.ctrl; + + // Enable the wallet (request connection) + try { + const api = await cardanoWallet.enable(); + console.log('Connected to Ctrl wallet'); + + // Now you can use the API methods + const balance = await api.getBalance(); + const addresses = await api.getUsedAddresses(); + + } catch (error) { + console.error('Failed to connect:', error); + } +} else { + console.log('Ctrl (fka XDEFI) is not installed'); +} +``` + +### Basic API + +Please find the Full Basic API on [CIP-30 specification](https://cips.cardano.org/cip/CIP-30) + +#### Connect using `enable` + +```javascript +enable(): Promise +``` + +The `window.cardano.ctrl.enable()` method requests the extension to be unlocked if it's currently locked. If the user hasn't given permission to the webpage, it will ask the user to give permission for the webpage to access XDEFI. This method follows the [CIP-30 enable specification](https://cips.cardano.org/cip/CIP-30). + +#### Get Network ID + +```javascript +getNetworkId(): Promise +``` + +Returns the network ID of the currently connected network. Returns `0` for testnet and `1` for mainnet. See [CIP-30 getNetworkId](https://cips.cardano.org/cip/CIP-30). + +#### Get Balance + +```javascript +getBalance(): Promise> +``` + +Returns the total balance available of the wallet as CBOR-encoded value. This is the same as summing the results of `getUtxos()`, but maintained by the wallet in a more efficient manner. See [CIP-30 getBalance](https://cips.cardano.org/cip/CIP-30). + +#### Get UTXOs + +```javascript +getUtxos(amount?: cbor, paginate?: Paginate): Promise[] | null> +``` + +Returns a list of all UTXOs (unspent transaction outputs) controlled by the wallet. If `amount` is provided, filters UTXOs by minimum value. See [CIP-30 getUtxos](https://cips.cardano.org/cip/CIP-30). + +#### Get Collateral + +```javascript +getCollateral(amount?: cbor): Promise[] | null> +``` + +Returns UTXOs suitable for use as collateral inputs for transactions with Plutus script witnesses. The maximum amount is typically 5 ADA. See [CIP-30 getCollateral](https://cips.cardano.org/cip/CIP-30). + +#### Get Used Addresses + +```javascript +getUsedAddresses(paginate?: Paginate): Promise +``` + +Returns a list of all used addresses controlled by the wallet. These are addresses that have been included in some on-chain transaction. See [CIP-30 getUsedAddresses](https://cips.cardano.org/cip/CIP-30). + +#### Get Unused Addresses + +```javascript +getUnusedAddresses(): Promise +``` + +Returns a list of unused addresses controlled by the wallet. See [CIP-30 getUnusedAddresses](https://cips.cardano.org/cip/CIP-30). + +#### Get Change Address + +```javascript +getChangeAddress(): Promise
+``` + +Returns an address owned by the wallet that should be used as a change address to return leftover assets during transaction creation. See [CIP-30 getChangeAddress](https://cips.cardano.org/cip/CIP-30). + +#### Get Reward Addresses + +```javascript +getRewardAddresses(): Promise +``` + +Returns the reward addresses owned by the wallet. This can return multiple addresses for multi-stake-keys wallets. See [CIP-30 getRewardAddresses](https://cips.cardano.org/cip/CIP-30). + +#### Sign Transaction + +```javascript +signTx(tx: cbor, partialSign?: bool): Promise> +``` + +Requests that a user sign the unsigned portions of the supplied transaction. If `partialSign` is true, the wallet only tries to sign what it can. See [CIP-30 signTx](https://cips.cardano.org/cip/CIP-30). + +#### Sign Data + +```javascript +signData(addr: Address, payload: Bytes): Promise +``` + +This endpoint utilizes the CIP-0008 signing spec for standardization/safety reasons. It allows the dApp to request the user to sign a payload conforming to said spec. See [CIP-30 signData](https://cips.cardano.org/cip/CIP-30). + +#### Submit Transaction + +```javascript +submitTx(tx: cbor): Promise +``` + +Requests that a transaction be sent through the wallet. Returns the transaction ID for the dApp to track. See [CIP-30 submitTx](https://cips.cardano.org/cip/CIP-30). + +For more details, refer to the [CIP-30 Cardano dApp-Wallet Web Bridge](https://cips.cardano.org/cip/CIP-30) specification. diff --git a/developers/extension-wallet.md b/developers/extension-wallet.md index 8405f2dd9..eac686e2d 100644 --- a/developers/extension-wallet.md +++ b/developers/extension-wallet.md @@ -24,3 +24,6 @@ Ctrl Wallet injects into the window object to dapps multiple wallet providers to - window.xfi.tron: [Tron provider](./extension-tron) - window.ethereum : [Ethereum provider](./extension-evms) - window.keplr : [Keplr/Cosmos chains provider](./extension-cosmos) +- window.cardano + - window.cardano.ctrl: [Cardano provider](./extension-cardano) + - window.cardano.xdefi: [Cardano provider](./extension-cardano) diff --git a/developers/introduction.md b/developers/introduction.md index 57733a24c..1c77f9cd7 100644 --- a/developers/introduction.md +++ b/developers/introduction.md @@ -12,7 +12,7 @@ Welcome developers! You are now ready to implement Ctrl (fka XDEFI) and level up You will found here direct access to all subtopics depending on your needs. -Don't hesitate to join our [Discord channel](https://discord.gg/xdefi) and ask any questions related to your developer experience with the community. +Don't hesitate to join our [Discord channel](https://discord.gg/ctrlwallet) and ask any questions related to your developer experience with the community. ## Ctrl Wallet integration