From f1cacace5d1cdf91af3aae19bca155acec7551ad Mon Sep 17 00:00:00 2001 From: 0xBora <0xquantive@gmail.com> Date: Sun, 15 Dec 2024 01:17:38 +0100 Subject: [PATCH] docs(update): vertical display refined --- .../core-concepts/instantiate-evolution.mdx | 36 +++- .../documentation/deep-dives/conway-era.mdx | 146 +++++++-------- .../deep-dives/make-payments.mdx | 170 +++++++++--------- .../documentation/deep-dives/mint-assets.mdx | 15 ++ .../smart-contract-interactions.mdx | 6 - docs/theme.config.jsx | 2 +- 6 files changed, 208 insertions(+), 167 deletions(-) diff --git a/docs/pages/documentation/core-concepts/instantiate-evolution.mdx b/docs/pages/documentation/core-concepts/instantiate-evolution.mdx index 25f4e1d6..df2c53c0 100644 --- a/docs/pages/documentation/core-concepts/instantiate-evolution.mdx +++ b/docs/pages/documentation/core-concepts/instantiate-evolution.mdx @@ -21,6 +21,8 @@ const lucid = await Lucid( ); ``` +--- + ### Kupmios ```typescript @@ -34,8 +36,12 @@ const lucid = await Lucid( "Preview" ); ``` + + Kupmios is a mix of [Ogmios](https://ogmios.dev/) and [Kupo](https://cardanosolutions.github.io/kupo/). + +--- ### Maestro @@ -52,6 +58,8 @@ const lucid = await Lucid( ); ``` +--- + ### Koios ```typescript @@ -63,6 +71,8 @@ const lucid = await Lucid( ); ``` +--- + ### YACI DevKit YACI DevKit provides a local development environment with configurable block times and network parameters. For detailed setup instructions, visit the [YACI DevKit documentation](https://devkit.yaci.xyz/tutorials/lucid-evolution/overview). @@ -83,6 +93,8 @@ const lucid = await Lucid( ); ``` +--- + ### UTxORPC ```typescript //TODO: https://github.com/utxorpc/lucid-evolution-provider @@ -96,13 +108,15 @@ The `provider` in `lucid.provider` is the provider instance you passed to `Lucid ### Query UTxOs -#### Using Provider +**Using Provider** ```typescript const utxos = await lucid.provider.getUtxos("addr_test..."); ``` -#### Using Convenience Method +--- + +**Using Convenience Method** ```typescript const utxos = await lucid.utxosAt("addr_test..."); @@ -112,21 +126,27 @@ const utxos = await lucid.utxosAt("addr_test..."); This convenience method internally uses `lucid.provider.getUtxos()`. +--- + ### Query Datums -#### Using Provider +**Using Provider** ```typescript const datum = await lucid.provider.getDatum(""); ``` -#### Using Convenience Method +--- + +**Using Convenience Method** ```typescript const datum = await lucid.datumOf(""); ``` -#### Querying datum from a UTxO: +--- + +**Querying datum from a UTxO** ```typescript const [scriptUtxo] = await lucid.utxosAt("addr_test..."); @@ -134,13 +154,15 @@ const datum = await lucid.datumOf(scriptUtxo); ``` -`lucid.datumOf(scriptUtxo)` is a convenience method that internally uses `lucid.provider.getDatum()` if the datum isn't already attached to the UTxO. When you query the datum for a UTxO, Lucid automatically adds the datum to the UTxO. This means that subsequent queries for the same UTxO will return the result instantly, without the need for an additional network request. +`lucid.datumOf(scriptUtxo)` is a convenience method that internally uses `lucid.provider.getDatum()` if the datum isn't already attached to the UTxO. + +When you query the datum for a UTxO, Lucid automatically adds the datum to the UTxO. This means that subsequent queries for the same UTxO will return the result instantly, without the need for an additional network request. ### Query Protocol Parameters -Using the provider directly: +**Using the provider directly:** ```typescript const protocolParameters = await lucid.provider.getProtocolParameters(); diff --git a/docs/pages/documentation/deep-dives/conway-era.mdx b/docs/pages/documentation/deep-dives/conway-era.mdx index 04759582..dbdc4f5d 100644 --- a/docs/pages/documentation/deep-dives/conway-era.mdx +++ b/docs/pages/documentation/deep-dives/conway-era.mdx @@ -5,56 +5,56 @@ import Link from 'next/link'; The Conway era introduces significant on-chain governance features to the Cardano blockchain, as outlined in [CIP-1694](https://github.com/cardano-foundation/CIPs/tree/master/CIP-1694). These enhancements enable ADA holders to participate in various on-chain decisions. Lucid Evolution now supports key governance actions, allowing users to engage in the democratic process of the Cardano ecosystem. -Governance functionality documentation is actively being updated to reflect the latest features 🛠️ - ## For ADA Holders As an ADA holder, you can participate in governance through various voting strategies and delegation options. - + To be able to delegate your voting power, you must first register the associated stake address and query the reward address. Learn more about stake address registration [here](/documentation/deep-dives/register-stake). ### Voting Delegation -#### Delegate Vote - Delegate your voting power to a specific DRep: - ```typescript - await lucid.newTx() - .delegate.VoteToDRep(rewardAddress, drep) - ``` - -#### Register and Delegate - Register a stake address and delegate voting power to a DRep in one action: - ```typescript - await lucid.newTx() - .registerAndDelegate.ToDrep(rewardAddress, drep) - ``` - -#### Delegate Vote and Stake - - Delegate both your ADA stake to a pool and your voting power to a DRep in one action: - ```typescript - await lucid.newTx() - .delegate.VoteToPoolAndDrep(rewardAddress, poolId, drep) - ``` - - - You can also register a stake address, delegate to a pool, and vote to a DRep (e.g., `AlwaysAbstain`) in one action: - - ```typescript - await lucid.newTx() - .registerAndDelegate.ToPoolAndDRep(rewardAddress, poolId, { - __typename: "AlwaysAbstain", - }) - ``` - +**Delegate your voting power to a specific DRep:** + +```typescript +await lucid.newTx() + .delegate.VoteToDRep(rewardAddress, drep) +``` +--- +**Register a stake address and delegate voting power to a DRep in one action:** + +```typescript +await lucid.newTx() + .registerAndDelegate.ToDrep(rewardAddress, drep) +``` + +--- + +**Delegate both your ADA stake to a pool and your voting power to a DRep in one action:** + +```typescript +await lucid.newTx() + .delegate.VoteToPoolAndDrep(rewardAddress, poolId, drep) +``` + + +You can also register a stake address, delegate to a pool, and vote to a DRep (e.g., `AlwaysAbstain`) in one action: + +```typescript +await lucid.newTx() + .registerAndDelegate.ToPoolAndDRep(rewardAddress, poolId, { + __typename: "AlwaysAbstain", + }) +``` + --- ### Predefined Voting Strategies -#### Always Abstain +**Always Abstain:** + ```typescript await lucid.newTx() .delegate.VoteToDRep(rewardAddress, { @@ -62,7 +62,10 @@ await lucid.newTx() }) ``` -#### Always No Confidence +--- + +**Always No Confidence:** + ```typescript await lucid.newTx() .delegate.VoteToDRep(rewardAddress, { @@ -70,49 +73,50 @@ await lucid.newTx() }) ``` - -When using predefined strategies like `AlwaysAbstain` or `AlwaysNoConfidence`, ensure the DRep object has the `__typename` property set to the desired value - - ## For DReps As a Delegated Representative (DRep), you can manage your status and information on the network. ### Managing DRep Status - #### Register DRep - Register a stake address as a DRep: - ```typescript - await lucid.newTx() - .register.DRep(rewardAddress) - ``` +**Register a stake address as a DRep:** + +```typescript +await lucid.newTx() + .register.DRep(rewardAddress) +``` + - -Remember to register the associated stake address before registering as a DRep. This way you will be able to query the reward address and update the DRep information. Learn more about stake address registration [here](/documentation/deep-dives/register-stake). - -#### Update DRep +--- + +**Update DRep information:** + +```typescript +await lucid.newTx() + .updateDRep(rewardAddress) +``` + +--- - Update DRep information: - ```typescript - await lucid.newTx() - .updateDRep(rewardAddress) - ``` +**Deregister a DRep stake address:** -#### Deregister DRep - Deregister as a DRep: - ```typescript - await lucid.newTx() - .deregister.DRep(rewardAddress) - ``` +```typescript +await lucid.newTx() + .deregister.DRep(rewardAddress) +``` + +Remember to register the associated stake address before registering as a DRep. This way you will be able to query the reward address and update the DRep information. Learn more about stake address registration [here](/documentation/deep-dives/register-stake). + ## Script-based DReps Lucid Evolution supports script-based DReps, enabling programmatic voting behavior for more complex governance strategies - - - +--- + +**Register Script DRep:** + ```typescript await lucid .newTx() @@ -120,19 +124,17 @@ await lucid .attach.Script(script) ``` - - +--- + +**Deregister Script DRep:** + ```typescript await lucid .newTx() .deregister.DRep(rewardAddress) ``` - - - - - +--- ## Example diff --git a/docs/pages/documentation/deep-dives/make-payments.mdx b/docs/pages/documentation/deep-dives/make-payments.mdx index 18c53fc6..d9828290 100644 --- a/docs/pages/documentation/deep-dives/make-payments.mdx +++ b/docs/pages/documentation/deep-dives/make-payments.mdx @@ -18,26 +18,29 @@ For straightforward payments to a public key or native script address, use `pay. const txHash = await signedTx.submit(); ``` +--- ### Multiple Recipients Chain multiple `pay.ToAddress` calls to pay multiple recipients: - ```typescript - const tx = await lucid - .newTx() - .pay.ToAddress("addr_testa...", { lovelace: 5000000n }) - .pay.ToAddress("addr_testb...", { lovelace: 5000000n }) - .pay.ToAddress("addr_testc...", { lovelace: 5000000n }) - .complete(); +```typescript +const tx = await lucid + .newTx() + .pay.ToAddress("addr_testa...", { lovelace: 5000000n }) + .pay.ToAddress("addr_testb...", { lovelace: 5000000n }) + .pay.ToAddress("addr_testc...", { lovelace: 5000000n }) + .complete(); - const signedTx = await tx.sign.withWallet().complete(); - const txHash = await signedTx.submit(); - ``` +const signedTx = await tx.sign.withWallet().complete(); +const txHash = await signedTx.submit(); +``` - - Each `pay.ToAddress` call creates a new UTxO, even for the same address. Lucid Evolution considers the order of outputs. - + +Each `pay.ToAddress` call creates a new UTxO, even for the same address. Lucid Evolution considers the order of outputs. + + +--- ### Native Tokens @@ -56,33 +59,36 @@ Lucid Evolution automatically adds the minimum ADA requirement for payments in C const txHash = await signedTx.submit(); ``` - +--- ### Attach Metadata Attach metadata to your ADA payments: - ```typescript - const tx = await lucid - .newTx() - .pay.ToAddress("addr_test...", { lovelace: 5000000n }) - .attachMetadata(1, { msg: "Hello from Anastasia Labs" }) - .complete(); +```typescript +const tx = await lucid + .newTx() + .pay.ToAddress("addr_test...", { lovelace: 5000000n }) + .attachMetadata(1, { msg: "Hello from Anastasia Labs" }) + .complete(); - const signedTx = await tx.sign.withWallet().complete(); - const txHash = await signedTx.submit(); - ``` +const signedTx = await tx.sign.withWallet().complete(); +const txHash = await signedTx.submit(); +``` -### Datum/Script +--- + +### Datum / Reference Script For more complex scenarios, `pay.ToAddressWithData` allows you to include a datum or a reference script. Lucid Evolution then implicitly adds the minimum ADA requirement for datums. - - - The datum can be attached in different ways: - ```typescript - // As hash - datum is attached to the witness set, with its hash stored in the UTxO - const tx = await lucid - .newTx() +**With a Datum** + +The datum can be attached in different ways: + +```typescript +// As hash - datum is attached to the witness set, with its hash stored in the UTxO +const tx = await lucid + .newTx() .pay.ToAddressWithData( "addr_test...", { kind: "hash", value: Data.to("31313131") }, @@ -90,66 +96,68 @@ For more complex scenarios, `pay.ToAddressWithData` allows you to include a datu ) .complete(); - // As inline - datum stored directly in UTxO - const tx = await lucid - .newTx() +// As inline - datum stored directly in UTxO +const tx = await lucid + .newTx() .pay.ToAddressWithData( "addr_test...", { kind: "inline", value: Data.to("31313131") }, { lovelace: 5000000n } ) .complete(); - ``` - - - - ```typescript - // Deploy a reference script - const deployRefScriptTx = await lucid - .newTx() - .pay.ToAddressWithData( - scriptAddress, - { kind: "inline", value: datum }, - { lovelace: 5_000_000n }, - referenceScript // The script to be stored as a reference for subsequent transactions - ) - .complete(); - ``` +``` - ```typescript - // Later, transactions can reference the deployed script instead of including it - // For example: +--- - const allUTxOs = await lucid.utxosAt(scriptAddress); - const refScriptUTxO = allUTxOs.filter(utxo => utxo.scriptRef); // Find UTxO with reference script depending on your use case - - const useRefScriptTx = await lucid - .newTx() - .collectFrom([utxoToSpend], redeemer) // Specify your action, for example: which UTxO to spend and which redeemer to use - .readFrom([refScriptUTxO]) // Reference the script UTxO - .complete(); - ``` - - Reference scripts are stored on-chain in a UTxO and can be "referenced" by other transactions, reducing transaction sizes and costs. This way the script only needs to be stored once and can be reused by multiple transactions. - - - +**With Script Reference** + +Deploy a reference script: + +```typescript +const deployRefScriptTx = await lucid + .newTx() + .pay.ToAddressWithData( + scriptAddress, + { kind: "inline", value: datum }, + { lovelace: 5_000_000n }, + referenceScript // The script to be stored as a reference for subsequent transactions + ) + .complete(); +``` + +Later, transactions can reference the deployed script instead of including it, for example: + +```typescript +const allUTxOs = await lucid.utxosAt(scriptAddress); +const refScriptUTxO = allUTxOs.filter(utxo => utxo.scriptRef); // Find UTxO with reference script depending on your use case + +const useRefScriptTx = await lucid + .newTx() + .collectFrom([utxoToSpend], redeemer) // Specify your action, for example: which UTxO to spend and which redeemer to use + .readFrom([refScriptUTxO]) // Reference the script UTxO + .complete(); +``` + + +Reference scripts are stored on-chain in a UTxO and can be "referenced" by other transactions, reducing transaction sizes and costs. This way the script only needs to be stored once and can be reused by multiple transactions. + + +--- - ### Plutus Script Use `pay.ToContract` for payments to a Plutus script address. This method ensures that a datum is provided. - ```typescript - const tx = await lucid - .newTx() - .pay.ToContract( - "addr_test...", - { kind: "inline", value: Data.to("31313131") }, - { lovelace: 5000000n } - ) - .complete(); - - const signedTx = await tx.sign.withWallet().complete(); - const txHash = await signedTx.submit(); - ``` +```typescript +const tx = await lucid + .newTx() + .pay.ToContract( + "addr_test...", + { kind: "inline", value: Data.to("31313131") }, + { lovelace: 5000000n } + ) + .complete(); + +const signedTx = await tx.sign.withWallet().complete(); +const txHash = await signedTx.submit(); +``` diff --git a/docs/pages/documentation/deep-dives/mint-assets.mdx b/docs/pages/documentation/deep-dives/mint-assets.mdx index 3efbf987..879b38cb 100644 --- a/docs/pages/documentation/deep-dives/mint-assets.mdx +++ b/docs/pages/documentation/deep-dives/mint-assets.mdx @@ -103,6 +103,21 @@ address, .complete(); ``` + + +An alternative way to define the metadata is to use an object: + +```typescript +const metadataObject = { + [fromText("myKey")]: Data.to(fromText("myValue")) +} + +const metadataCBOR = Data.to( + { metadata: new Map(Object.entries(metadataObject)), version: 0n }, + CIP68Datum +); +``` + --- ## Burn diff --git a/docs/pages/documentation/deep-dives/smart-contract-interactions.mdx b/docs/pages/documentation/deep-dives/smart-contract-interactions.mdx index 60c3234e..9ca0cc58 100644 --- a/docs/pages/documentation/deep-dives/smart-contract-interactions.mdx +++ b/docs/pages/documentation/deep-dives/smart-contract-interactions.mdx @@ -274,9 +274,3 @@ const tx = await lucid --- - -## Troubleshooting - - -If you encounter a `TxBuilderError` with `{ Complete: {} }` when building transactions with Aiken contracts, try adding `.complete({localUPLCEval: false})` to your transaction builder. This bypasses the local cost model estimation and lets the TxBuilder handle execution units, which can help resolve mismatches between Aiken and Lucid Evolution's cost models. - \ No newline at end of file diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx index f7f0ae2d..79ee1d6d 100644 --- a/docs/theme.config.jsx +++ b/docs/theme.config.jsx @@ -56,7 +56,7 @@ export default { href="https://github.com/Anastasia-Labs/lucid-evolution/releases" target="_blank" > - ❤️ Support Lucid Evolution in Fund 13 - Your vote can help shape the future of Cardano Developer Experience! + Check out our latest release! → ),