From 1e869abf3732f106de749b847becfe634667868e Mon Sep 17 00:00:00 2001 From: 0xBora <0xquantive@gmail.com> Date: Fri, 7 Mar 2025 23:22:35 +0100 Subject: [PATCH] Refresh content structure - lucid evolution --- docs/get-started/lucid-evolution.md | 206 ------------------ .../lucid-evolution/get-started.md | 164 ++++++++++++++ .../lucid-evolution/transactions.md | 103 +++++++++ docs/get-started/lucid-evolution/wallets.md | 109 +++++++++ sidebars.js | 11 +- 5 files changed, 386 insertions(+), 207 deletions(-) delete mode 100644 docs/get-started/lucid-evolution.md create mode 100644 docs/get-started/lucid-evolution/get-started.md create mode 100644 docs/get-started/lucid-evolution/transactions.md create mode 100644 docs/get-started/lucid-evolution/wallets.md diff --git a/docs/get-started/lucid-evolution.md b/docs/get-started/lucid-evolution.md deleted file mode 100644 index c0fac5ff50..0000000000 --- a/docs/get-started/lucid-evolution.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -id: lucid-evolution -title: Get Started with Lucid Evolution -sidebar_label: Lucid Evolution -description: Get Started with Lucid Evolution ---- - -Lucid Evolution is a highly scalable, production-ready transaction builder & off-chain framework for users and dApps. - -## Installation - -To install `lucid-evolution` you can use `pnpm` (or another package manager) and run the following in you root project: - -#### Add `lucid-evolution` as dependency - -```sh -pnpm i @lucid-evolution/lucid -``` - -#### Get `lucid-evolution` from source - -First clone the git repository - -```sh -git clone https://github.com/Anastasia-Labs/lucid-evolution.git -cd lucid-evolution -pnpm install -``` - -## Instantiate Lucid Evolution - -Lucid Evolution can be used with or without a blockchain provider, which allows you to query data and submit transactions. - -Evolution supports the `Mainnet`, `Preprod`, `Preview` and `Custom` networks - -### Provider selection - -There are multiple builtin providers you can choose from in Lucid Evolution not limited to: - -#### Blockfrost - -```typescript -import { Lucid, Blockfrost } from "@lucid-evolution/lucid"; - -const lucid = await Lucid( - new Blockfrost("https://cardano-preprod.blockfrost.io/api/v0", ""), - "Preprod" -); -``` - -#### Kupmios - -```typescript -import { Lucid, Kupmios } from "@lucid-evolution/lucid"; - -const lucid = await Lucid( - new Kupmios( - "http://localhost:1442", // Kupo endpoint - "http://localhost:1337" // Ogmios endpoint (Note: changed from ws:// to http:// in a release 1 month ago) - ), - "Preview" -); -``` - -Kupmios is a mix of [Ogmios](https://ogmios.dev/) and [Kupo](https://cardanosolutions.github.io/kupo/). - -#### Maestro - -```typescript -import { Lucid, Maestro } from "@lucid-evolution/lucid"; - -const lucid = await Lucid( - new Maestro({ - network: "Preprod", // For MAINNET: "Mainnet" - apiKey: "", // Get yours by visiting https://docs.gomaestro.org/docs/Getting-started/Sign-up-login - turboSubmit: false, // Read about paid turbo transaction submission feature at https://docs.gomaestro.org/docs/Dapp%20Platform/Turbo%20Transaction - }), - "Preprod" // For MAINNET: "Mainnet" -); -``` - -#### Koios - -```typescript -import { Lucid, Koios } from "@lucid-evolution/lucid"; - -const lucid = await Lucid( - new Koios("https://preprod.koios.rest/api/v1"), - "Preprod" -); -``` - -### Query Provider - -The `provider` in `lucid.provider` is the provider instance you passed to `Lucid()` when selecting your provider (Blockfrost, Kupmios, Maestro, Koios, etc.). - -#### Query UTxOs - -#### Using Provider - -```typescript -const utxos = await lucid.provider.getUtxos("addr_test..."); -``` - -#### Using Convenience Method - -```typescript -const utxos = await lucid.utxosAt("addr_test..."); -``` - -This convenience method internally uses `lucid.provider.getUtxos()`. - -#### Query Datums - -##### Using Provider - -```typescript -const datum = await lucid.provider.getDatum(""); -``` - -##### Using Convenience Method - -```typescript -const datum = await lucid.datumOf(""); -``` - -##### Querying datum from a UTxO - -```typescript -const [scriptUtxo] = await lucid.utxosAt("addr_test..."); -const datum = await lucid.datumOf(scriptUtxo); -``` - - -#### Query Protocol Parameters - -##### Using the provider directly: - -```typescript -const protocolParameters = await lucid.provider.getProtocolParameters(); -``` - -## Create a wallet - -You are provided multiple options to create and import a wallet - -### Private Key - Generate a new private key: - - ```typescript - const privateKey = generatePrivateKey(); // Bech32 encoded private key - console.log(privateKey); - ``` - -### Seed Phrase - -Generate a new seed phrase (mnemonic): - - ```typescript - const seedPhrase = generateSeedPhrase(); // BIP-39 - console.log(seedPhrase); - ``` - -## Choosing Wallet - -Use different methods to select a wallet and query balances, UTxOs - - -### Private Key - - Select a wallet using a private key: - - ```typescript - lucid.selectWallet.fromPrivateKey(privateKey); - ``` - -### Address & UTXOs - -This method is useful when you have the address and UTXOs of a wallet but not necessarily the private key. - ```typescript - const address = "addr_test..."; // Your wallet address - const utxos = await lucid.utxosAt(address); - lucid.selectWallet.fromAddress(address, utxos); - ``` - -### Seed Phrase - - Select a wallet using a seed phrase (mnemonic): - - ```typescript - const seedPhrase = "your seed phrase here..."; - lucid.selectWallet.fromSeed(seedPhrase); - ``` - - -If you're integrating with a wallet provider that exposes an API conforming to the WalletApi interface: - - ```typescript - // `externalWalletApi` is your wallet provider's API - const walletApi: WalletApi = externalWalletApi; - lucid.selectWallet.fromAPI(walletApi); - ``` - -## More examples - -You now have all you need to start playing with Lucid Evolution. Have a look at [our docs](https://anastasia-labs.github.io/lucid-evolution/documentation/core-concepts/instantiate-evolution) for more examples. diff --git a/docs/get-started/lucid-evolution/get-started.md b/docs/get-started/lucid-evolution/get-started.md new file mode 100644 index 0000000000..0e0675f902 --- /dev/null +++ b/docs/get-started/lucid-evolution/get-started.md @@ -0,0 +1,164 @@ +--- +id: get-started +sidebar_position: 1 +title: Get Started with Lucid Evolution +sidebar_label: Instantiate Evolution +description: Quick start guide for Lucid Evolution +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Get Started with Lucid Evolution + +Lucid Evolution is a highly scalable, production-ready transaction builder & off-chain framework for users and DApps. It provides a TypeScript library for building transactions and designing off-chain code. + +In this guide, we will walk you through just 3 easy steps to install the `lucid-evolution` package, instantiate the Lucid Evolution library, create/choose a wallet, and build and submit a transaction. The library is capable of much more and is one of the popular tools for building off-chain code for Cardano dApps. + +> For more examples and use cases, please refer to the official Lucid Evolution [documentation](https://anastasia-labs.github.io/lucid-evolution/documentation/deep-dives/make-payments). + +> Come say hi on [Discord](https://discord.gg/G9GbN2CVTR) if you have any questions! + +## Installation + + + + +```bash +pnpm i @lucid-evolution/lucid +``` + + + + +```bash +npm i @lucid-evolution/lucid +``` + + + + +```bash +yarn add @lucid-evolution/lucid +``` + + + + +```bash +bun i @lucid-evolution/lucid +``` + + + + +:::note + +Installing the `lucid` package will automatically export all other Lucid Evolution packages as well. For more information on more granular package definitions for lightweight development, please refer to the the Evolution library [installation guide](https://anastasia-labs.github.io/lucid-evolution/install). + +::: + +## Instantiate Lucid Evolution + +Lucid Evolution can be used with or without a blockchain provider, which allows you to query data and submit transactions. Evolution library supports the `Mainnet`, `Preprod`, `Preview` and `Custom` networks. + +### Provider Selection + + + + +```typescript +import { Lucid, Blockfrost } from "@lucid-evolution/lucid"; + +const lucid = await Lucid( + new Blockfrost("https://cardano-preprod.blockfrost.io/api/v0", ""), + "Preprod" +); +``` + + + + +```typescript +import { Lucid, Kupmios } from "@lucid-evolution/lucid"; + +const lucid = await Lucid( + new Kupmios( + "http://localhost:1442", // Kupo endpoint + "http://localhost:1337" // Ogmios endpoint + ), + "Preview" +); +``` + +**or with API Keys** + +```typescript +const lucid = await Lucid( + new Kupmios("http://localhost:1442", "http://localhost:1337", { + kupoHeader: { "priv-api-key": "" }, // for example: "dmtr-api-key": "" + ogmiosHeader: { "priv-api-key": "" }, + }), + "Preview" +); +``` + +:::note + +Kupmios is a mix of [Ogmios](https://ogmios.dev/) and [Kupo](https://cardanosolutions.github.io/kupo/). + +::: + + + + +```typescript +import { Lucid, Maestro } from "@lucid-evolution/lucid"; + +const lucid = await Lucid( + new Maestro({ + network: "Preprod", // For MAINNET: "Mainnet" (1) + apiKey: "", // Get yours by visiting https://docs.gomaestro.org/docs/Getting-started/Sign-up-login + turboSubmit: false, // Read about paid turbo transaction submission feature at https://docs.gomaestro.org/docs/Dapp%20Platform/Turbo%20Transaction + }), + "Preprod" // For MAINNET: "Mainnet" (2) +); +``` + + + + +```typescript +import { Lucid, Koios } from "@lucid-evolution/lucid"; + +const lucid = await Lucid( + new Koios("https://preprod.koios.rest/api/v1"), + "Preprod" +); +``` + +**or with a bearer token** + +```typescript +const lucid = await Lucid( + new Koios("", ""), + "Preprod" +); +``` + + + diff --git a/docs/get-started/lucid-evolution/transactions.md b/docs/get-started/lucid-evolution/transactions.md new file mode 100644 index 0000000000..8d740bca28 --- /dev/null +++ b/docs/get-started/lucid-evolution/transactions.md @@ -0,0 +1,103 @@ +--- +id: transactions +sidebar_position: 3 +title: Transactions +sidebar_label: Your First Transaction +description: How to build, sign, and submit transactions with Lucid Evolution +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Your first transaction + +A couple of fundamentals to remember are that in Cardano's eUTxO model, a transaction can consume one or more UTxOs as inputs, create one or more UTxOs as outputs, and must be balanced (sum of inputs = sum of outputs + fees). + +### 1. Build + +Let's create a simple transaction where we send `5 ada` to two recipients each: + +```typescript +const tx = await lucid + .newTx() + .pay.ToAddress("addr_testa...", { lovelace: 5000000n }) + .pay.ToAddress("addr_testb...", { lovelace: 5000000n }) + .complete(); +``` + +:::note +To balance the transaction and initiate coin selection, transactions always +need to end with `.complete()` +::: + +### 2. Sign + +```typescript +const signedTx = await tx.sign.withWallet().complete(); +``` + +You could also choose to sign the transaction with a private key: + +```typescript +const signedTx = await tx.sign.withPrivateKey(privateKey).complete(); +``` + +### 3. Submit + +Lastly we submit the transaction: + +```typescript +const txHash = await signedTx.submit(); +console.log(txHash); +``` + +:::note + +The wallet selection methods we discussed in the [previous section](wallets.md) should be implemented before building the transaction. + +::: + +## Putting everything together + +```typescript +import { Lucid, Blockfrost } from "@lucid-evolution/lucid"; + +// Initialize Lucid with a provider +const lucid = await Lucid( + new Blockfrost("https://cardano-preprod.blockfrost.io/api/v0", ""), + "Preprod" +); + +// Select a wallet for signing - in this case we're using a private key +lucid.selectWallet.fromPrivateKey(privateKey); + +// Build, sign and submit transaction +const tx = await lucid + .newTx() + .pay.ToAddress("addr_testa...", { lovelace: 5000000n }) // Pay 5 ada to addr_testa + .complete(); // Balances the transaction and initiates coin selection + +const signedTx = await tx.sign.withWallet().complete(); +const txHash = await signedTx.submit(); +console.log(txHash); +``` + +## You want to learn more? + +### Next Steps + +Explore the following sections to learn more about Lucid Evolution: + +- [Under the hood](https://anastasia-labs.github.io/lucid-evolution/documentation/core-concepts/under-the-hood) - Understand how Evolution library works +- [Deep dives](https://anastasia-labs.github.io/lucid-evolution/documentation/deep-dives/make-payments) - Follow this series in order to step-by-step understand how to build your own off-chain code for different/advanced use cases + +### Video Tutorial + + + +## Resources + +- [Official Evolution Library Documentation](https://anastasia-labs.github.io/lucid-evolution/documentation/core-concepts/instantiate-evolution) +- [GitHub Repository](https://github.com/anastasia-labs/lucid-evolution) + +> You now have all you need to start playing around with Lucid Evolution. If you have any questions, please refer to the library's [Discord community](https://discord.gg/G9GbN2CVTR). \ No newline at end of file diff --git a/docs/get-started/lucid-evolution/wallets.md b/docs/get-started/lucid-evolution/wallets.md new file mode 100644 index 0000000000..1c60b14610 --- /dev/null +++ b/docs/get-started/lucid-evolution/wallets.md @@ -0,0 +1,109 @@ +--- +id: wallets +sidebar_position: 2 +title: Create & Choose Wallets +sidebar_label: Create & Choose Wallets +description: How to create and choose wallets with Lucid Evolution +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Create a wallet + +You are provided with multiple options to create and import a wallet: + + + + +Generate a new private key: + +```typescript +import { generatePrivateKey } from "@lucid-evolution/lucid"; + +const privateKey = generatePrivateKey(); // Bech32 encoded private key +// console.log(privateKey); +``` + + + + +Generate a new seed phrase (mnemonic): + +```typescript +import { generateSeedPhrase } from "@lucid-evolution/lucid"; + +const seedPhrase = generateSeedPhrase(); // BIP-39 +// console.log(seedPhrase); +``` + + + + +--- + +## Choosing Wallet + +Use any suitable method to select a wallet and interact with the blockchain through it: + + + + +Select a wallet using a private key: + +```typescript +lucid.selectWallet.fromPrivateKey(privateKey); +``` + + + + +Select a wallet using a seed phrase (mnemonic): + +```typescript +const seedPhrase = "your seed phrase here..."; +lucid.selectWallet.fromSeed(seedPhrase); +``` + + + + +If you're integrating with a wallet provider that exposes an API conforming to the `WalletApi` interface. This works for any [CIP-30](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0030) compliant wallet. + +```typescript +// `externalWalletApi` is your wallet provider's API +const walletApi: WalletApi = externalWalletApi; +lucid.selectWallet.fromAPI(walletApi); +``` + + + + +This method will create a limited wallet that can still query the address and its UTxOs. You can use it to build transactions that **others will sign**, as it cannot sign transactions (no private key). + +```typescript +const address = "addr_test..."; +const utxos = await lucid.utxosAt(address); +lucid.selectWallet.fromAddress(address, utxos); +``` + +:::warning + +Transactions built with an address-only wallet will need to be signed by a wallet with the actual private keys before they can be submitted. + +::: + + + diff --git a/sidebars.js b/sidebars.js index df2b3f54e0..ffe2ee9d7f 100644 --- a/sidebars.js +++ b/sidebars.js @@ -61,7 +61,16 @@ module.exports = { "get-started/cscli", "get-started/dandelion-apis", "get-started/koios", - "get-started/lucid-evolution", + { + type: "category", + label: "Lucid Evolution", + items: [ + { + type: "autogenerated", + dirName: "get-started/lucid-evolution", + }, + ], + }, { type: "category", label: "Mesh (Web3 SDK)",