From c7a2247f32630ad925f35fe3efd26008f6e78370 Mon Sep 17 00:00:00 2001 From: Satya Date: Tue, 30 Jan 2024 19:23:09 +0800 Subject: [PATCH 1/2] chore: Added governance api doc --- docs/docs/Apis/_category_.json | 7 + docs/docs/Apis/cip68-api.md | 23 +++ docs/docs/Apis/governance-api.md | 305 +++++++++++++++++++++++++++++++ docs/docs/Guides/_category_.json | 2 +- 4 files changed, 336 insertions(+), 1 deletion(-) create mode 100644 docs/docs/Apis/_category_.json create mode 100644 docs/docs/Apis/cip68-api.md create mode 100644 docs/docs/Apis/governance-api.md diff --git a/docs/docs/Apis/_category_.json b/docs/docs/Apis/_category_.json new file mode 100644 index 00000000..55515f67 --- /dev/null +++ b/docs/docs/Apis/_category_.json @@ -0,0 +1,7 @@ +{ + "label": "Apis", + "position": 3, + "link": { + "type": "generated-index" + } +} diff --git a/docs/docs/Apis/cip68-api.md b/docs/docs/Apis/cip68-api.md new file mode 100644 index 00000000..03373c9a --- /dev/null +++ b/docs/docs/Apis/cip68-api.md @@ -0,0 +1,23 @@ +--- +description: CIP68 Datum Metadata Api +sidebar_label: CIP68 Datum Metadata Api +sidebar_position: 2 +--- + +# CIP68 Datum Metadata Api + +**Version:** 0.5.1 and later + +## Introduction + +CIP68 defines a metadata standard for native assets making use of output datums not only for NFTs but any asset class. +Cardano Client Lib provides a simple API to build CIP68 compatible datum metadata and simplify the process of building transactions +to mint CIP68 compatible native tokens. + +[CIP68 - Datum Metadata Standard](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0068) + +### CIP68 NFT Datum Metadata Api + +```java + +``` diff --git a/docs/docs/Apis/governance-api.md b/docs/docs/Apis/governance-api.md new file mode 100644 index 00000000..69ee6154 --- /dev/null +++ b/docs/docs/Apis/governance-api.md @@ -0,0 +1,305 @@ +--- +description: Governance API Usage +sidebar_label: Governance Api +sidebar_position: 1 +--- + +# Governance Api (Preview) + +QuickTx Api now supports governance related transactions. It's supported through the existing `Tx` class. + +**Version:** 0.5.1 and later + +**Note:** This is a preview version and the API is subject to change. + +Check out QuickTx Governance API [**integration tests**](https://github.com/bloxbean/cardano-client-lib/blob/master/quicktx/src/it/java/com/bloxbean/cardano/client/quicktx/GovernanceTxIT.java) for more examples. + +## Pre-requisites +Create a `QuickTxBuilder` instance and required accounts. + +```java +QuickTxBuilder quickTxBuilder = new QuickTxBuilder(backendService); +Account accout = new Account("your mnemonic words"); +String address = account.baseAddress(); +``` + +## 1. DRep API + +**Note:** To find the DRepId of an account, you can use the `drepId()` method of the `Account` class. + +### Register DRep + +The following example shows how to register an account as a DRep. + +```java +var anchor = new Anchor("", ); + +Tx drepRegTx = new Tx() + .registerDRep(account, anchor) + .from(address); + +Result result = quickTxBuilder.compose(drepRegTx) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Deregister DRep + +To deregister an account as a DRep, use the `unregisterDRep()` method of the `Tx` class. The transaction needs to be +signed by the account for tx fee payment and by the DRep Key of the account., + +```java +Tx tx = new Tx() + .unregisterDRep(account.drepCredential()) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Update DRep + +To update the DRep information, use the `updateDRep()` method of the `Tx` class. The transaction needs to be signed +by the account for tx fee payment and by the DRep Key of the account. + +In the following example, the DRep information is updated to remove the anchor. + +```java + Tx drepRegTx = new Tx() + .updateDRep(account.drepCredential()) + .from(senderAddr); + +Result result = quickTxBuilder.compose(drepRegTx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +To update the DRep information with a new anchor. + +```java +var newAnchor = new Anchor("", ""); + +Tx drepRegTx = new Tx() + .updateDRep(account.drepCredential(), newAnchor) + .from(senderAddr); + +Result result = quickTxBuilder.compose(drepRegTx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +## 2. Gov Action Create API + +Using the `Tx` class, you can create a governance proposal such as + +- InfoAction +- NewConstitution +- NoConfidence +- ParameterChangeAction +- HardForkInitiationAction +- TreasuryWithdrawalsAction +- UpdateCommittee + + +Use the createProposal() method of the Tx class to create a proposal. In addition to the GovAction instance, you also need to +specify the amount of ADA to be deposited for the proposal creation and the return address (stake address) to which the +deposit will be returned. + +The transaction needs to be signed by the account for tx fee & deposit and by the DRep credential of the account. + +The required deposit amount for proposal creation is a protocol parameter (govActionDeposit) and it's currently set to 1000 ADA for Sanchonet. + +**Note:** In future versions, the deposit amount will be automatically fetched from the protocol parameters. + +### Create a Info Proposal + +Use `InfoAction` to create a proposal with anchor for proposal information. + +```java +var govAction = new InfoAction(); +var anchor = new Anchor("", ); + +Tx tx = new Tx() + .createProposal(govAction, adaToLovelace(1000), account.stakeAddress(), anchor) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Create new Constitution Proposal + +Use `NewConstitution` to create a proposal with anchor for new constitution. + +```java +var anchor = new Anchor("", ); + +var govAction = new NewConstitution(); +govAction.setPrevGovActionId(new GovActionId("", prevGovActionIndex)); +govAction.setConstitution(Constitution.builder() + .anchor(anchor) + .build()); + +Tx tx = new Tx() + .createProposal(govAction, adaToLovelace(1000), account.stakeAddress(), anchor) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Creae a NoConfidence Proposal + +Use `NoConfidence` to create a proposal for no confidence. + +```java +var noConfidence = new NoConfidence(); +noConfidence.setPrevGovActionId(new GovActionId("", prevGovActionIndex)); +var anchor = new Anchor("", ); + +Tx tx = new Tx() + .createProposal(noConfidence, adaToLovelace(1000), account.stakeAddress(), anchor) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Create a ParameterChange Proposal + +Use `ParameterChangeAction` to create a proposal for parameter change. + +In the below example, the minPoolCost parameter is updated to 100 ADA. + +```java +var parameterChange = new ParameterChangeAction(); +parameterChange.setPrevGovActionId(new GovActionId("529736be1fac33431667f2b66231b7b66d4c7a3975319ddac7cfb17dcb5c4145", 0)); +parameterChange.setProtocolParamUpdate(ProtocolParamUpdate.builder() + .minPoolCost(adaToLovelace(100)) + .build()); + +var anchor = new Anchor("", ); + +Tx tx = new Tx() + .createProposal(parameterChange, adaToLovelace(1000), account.stakeAddress(), anchor) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Create a HardForkInitiation Proposal + +Use `HardForkInitiationAction` to create a proposal for hard fork initiation. + +```java +var hardforkInitiation = new HardForkInitiationAction(); +hardforkInitiation.setPrevGovActionId(new GovActionId("416f7f01c548a85546aa5bbd155b34bb2802df68e08db4e843ef6da764cd8f7e", 0)); +hardforkInitiation.setProtocolVersion(new ProtocolVersion(9, 0)); + +var anchor = new Anchor("", ); + +Tx tx = new Tx() + .createProposal(hardforkInitiation, adaToLovelace(1000), account.stakeAddress(), anchor) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Create a TreasuryWithdrawal Proposal + +Use `TreasuryWithdrawalsAction` to create a proposal for treasury withdrawal. + +In the example below, a proposal is created to withdraw 20 ADA from the treasury and send it to the specified stake address. +```java +var treasuryWithdrawalsAction = new TreasuryWithdrawalsAction(); +treasuryWithdrawalsAction.addWithdrawal(new Withdrawal("stake_test1ur6l9f5l9jw44kl2nf6nm5kca3nwqqkccwynnjm0h2cv60ccngdwa", adaToLovelace(20))); + +var anchor = new Anchor("", ); + +Tx tx = new Tx() + .createProposal(treasuryWithdrawalsAction, adaToLovelace(1000), account.stakeAddress(), anchor) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +### Create a UpdateCommittee Proposal + +Use `UpdateCommittee` to create a proposal for updating the committee information. + +In the example below, a proposal is created to update the quorum threshold to 1/3. + +```java +var updateCommittee = new UpdateCommittee(); +updateCommittee.setPrevGovActionId(new GovActionId("b3ce0371310a07a797657d19453d953bb352b6841c2f5c5e0bd2557189ef5c3a", 0)); +updateCommittee.setQuorumThreshold(new UnitInterval(BigInteger.valueOf(1), BigInteger.valueOf(3))); + +var anchor = new Anchor("", ); + +Tx tx = new Tx() + .createProposal(updateCommittee, adaToLovelace(1000), account.stakeAddress(), anchor) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +## 3. Vote API + +Use the `Tx` class to vote on a governance proposal. + +In addition to the GovActionId, you also need to specify Vote(Yes, No, Abstain), voter and an anchor for the vote information (optional). + +The transaction needs to be signed by the account for tx fee payment and by the DRep credential of the account. + +```java +var voter = new Voter(VoterType.DREP_KEY_HASH, account.drepCredential()); +var govActionId = new GovActionId("5655fbb4ceafd34296fe58f6e3d28b8ff663a89e84aa0edd77bd02fe379cef4c", 0); //some gov action id + +Tx tx = new Tx() + .createVote(voter, govActionId, Vote.NO) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.drepKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` + +## 4. Vote Delegation API + +Use the `Tx` class to delegate voting rights to a DRep. + +```java +DRep drep = DRepId.toDrep(drepId, DRepType.ADDR_KEYHASH); + +Tx tx = new Tx() + .delegateVotingPowerTo(account, drep) + .from(address); + +Result result = quickTxBuilder.compose(tx) + .withSigner(SignerProviders.stakeKeySignerFrom(account)) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(s -> System.out.println(s)); +``` diff --git a/docs/docs/Guides/_category_.json b/docs/docs/Guides/_category_.json index f389501a..72a8c3ff 100644 --- a/docs/docs/Guides/_category_.json +++ b/docs/docs/Guides/_category_.json @@ -1,6 +1,6 @@ { "label": "Guides", - "position": 3, + "position": 4, "link": { "type": "generated-index" } From 287c25e7e0c2637e3bdb8912723f955970a2658c Mon Sep 17 00:00:00 2001 From: Satya Date: Tue, 30 Jan 2024 20:08:45 +0800 Subject: [PATCH 2/2] chore: Added cip68 api docs --- docs/docs/Apis/cip68-api.md | 108 +++++++++++++++++++++++++++++++++++- 1 file changed, 107 insertions(+), 1 deletion(-) diff --git a/docs/docs/Apis/cip68-api.md b/docs/docs/Apis/cip68-api.md index 03373c9a..e7f166fc 100644 --- a/docs/docs/Apis/cip68-api.md +++ b/docs/docs/Apis/cip68-api.md @@ -6,7 +6,7 @@ sidebar_position: 2 # CIP68 Datum Metadata Api -**Version:** 0.5.1 and later +**Version:** **0.5.1** and later ## Introduction @@ -16,8 +16,114 @@ to mint CIP68 compatible native tokens. [CIP68 - Datum Metadata Standard](https://github.com/cardano-foundation/CIPs/tree/master/CIP-0068) +## Dependencies + +- **Group Id :** com.bloxbean.cardano +- **Artifact Id:** cardano-client-cip68 + +## CIP68 Apis +Cardano Client Lib provides the following 3 main APIs to build CIP68 compatible datum metadata for different types of assets. +1. **CIP68NFT** : For NFTs (222 NFT Standard) +2. **CIP68FT** : For Fungible Tokens (333 Fungible Token Standard) +3. **CIP68RFT** : For Rich (444 Rich-FT Standard) + +Apart from the above APIs, there is an API **CIP68ReferenceToken** which is used for reference tokens. A reference token +instance can be created from the above 3 APIs. + ### CIP68 NFT Datum Metadata Api +The following example shows how to create a CIP68NFT instance and use it to mint a CIP68 NFT. + +In **Line 8**, create a CIP68NFT instance by calling the static method `CIP68NFT.create()`. Then set the name, description, +image and other properties of the NFT according to the CIP68 standard. + +In **Line 19**, get the corresponding CIP68ReferenceToken instance from CIP68NFT instance. + +In **Line 22**, get the Asset instance from CIP68ReferenceToken instance. This Asset instance can be used to mint the reference token. + +In **Line 25**, get the Asset instance from CIP68NFT instance. This Asset instance can be used to mint the user token. + +In **Line 28**, get the Datum from CIP68ReferenceToken instance. This Datum instance can be used to mint the reference token with CIP68 metadata +in datum. + +In **Line 37**, create a ScriptTx instance and define to mint the reference token and user token. + +```java showLineNumbers + //Minting Script +PlutusV2Script mintingScript = PlutusV2Script.builder() + .type("PlutusScriptV2") + .cborHex("...") + .build(); + +//Define CIP-68 compatible NFT metadata +CIP68NFT nft = CIP68NFT.create() + .name("MyCIP68NFT") + .image("https://xyz.com/image.png") + .description("A sample CIP-68 NFT") + .addFile(CIP68File.create() + .mediaType("image/png") + .name("image1.png") + .src("https://xyz.com/image.png") + ); + +//Get CIP68ReferenceToken from CIP68NFT +CIP68ReferenceToken referenceToken = nft.getReferenceToken(); + +//Create Reference Token Asset with quantity 1 +Asset referenzToken = referenceToken.getAsset(); + +//Create User Token Asset with quantity 1 +Asset userToken = nft.getAsset(BigInteger.valueOf(1)); + +//Get Datum from CIP68ReferenceToken +PlutusData datumMetadata = referenceToken.getDatumAsPlutusData(); + +//Receiver of the user token +String userTokenReceiver = receiverAddr; + +//Receiver of the reference token which is the minting script address +String referenceTokenReceiver = AddressProvider.getEntAddress(mintingScript, Networks.preprod()).toBech32(); + +//Define ScriptTx to mint Reference Token and User Token +ScriptTx scriptTx = new ScriptTx() + .mintAsset(mintingScript, List.of(referenzToken), PlutusData.unit(), referenceTokenReceiver, datumMetadata) + .mintAsset(mintingScript, List.of(userToken),PlutusData.unit(), userTokenReceiver); + +Result result = quickTxBuilder.compose(scriptTx) + .feePayer(account.baseAddress()) + .withSigner(SignerProviders.signerFrom(account)) + .completeAndWait(System.out::println); +``` + +### CIP68 FT Datum Metadata Api + +CIP68FT is used to mint CIP68 compatible Fungible Tokens (333). The following example shows how to create a CIP68FT instance. +From CIP68FT instance, you can get a CIP68ReferenceToken instance. The remaining steps are similar to previous section (CIP68NFT). + ```java +CIP68FT ft = CIP68FT.create() + .name("SampleFungibleToken") + .ticker("SFT") + .url("https://xyz.com") + .logo("https://xyz.com/logo.png") + .decimals(6) + .description("Sample CIP-68 FT"); +``` +### CIP68 RFT Datum Metadata Api + +CIP68RFT is used to mint CIP68 compatible Rich Fungible Tokens (444). The following example shows how to create a CIP68RFT instance. +From CIP68RFT instance, you can get a CIP68ReferenceToken instance. The remaining steps are similar to CIP68NFT section. + +```java +CIP68RFT rft = CIP68RFT.create() + .name("SampleRichFungibleToken") + .image("https://xyz.com/image.png") + .description("Sample CIP-68 RFT") + .addFile(CIP68File.create() + .mediaType("image/png") + .name("image.png") + .src("https://xyz.com/image.png") + ) + .property("", ""); ```