From 4f0c63dad4b465d3181d3cc04b676a412c1a2a25 Mon Sep 17 00:00:00 2001 From: Willem Wyndham Date: Mon, 25 Nov 2024 16:53:11 -0500 Subject: [PATCH] docs: add examples of using `tx new`, `sign`, `send`, and `op add` Currently relies on unmerged PRs. --- cookbook/tx-new.mdx | 187 +++++++++++++++++++++++++++++++++++++++++ cookbook/tx-op-add.mdx | 51 +++++++++++ cookbook/tx-sign.mdx | 72 ++++++++++++++++ 3 files changed, 310 insertions(+) create mode 100644 cookbook/tx-new.mdx create mode 100644 cookbook/tx-op-add.mdx create mode 100644 cookbook/tx-sign.mdx diff --git a/cookbook/tx-new.mdx b/cookbook/tx-new.mdx new file mode 100644 index 000000000..481d13d59 --- /dev/null +++ b/cookbook/tx-new.mdx @@ -0,0 +1,187 @@ +--- +title: `tx` Commands +hide_table_of_contents: true +description: Create stellar transactions using the Stellar CLI +--- + +So far the examples of the CLI interacting with the blockchain have been through the `contract` command. Uploading contracts, deploying contracts, and invoking them. +Each of these are different types of transactions, which must be signed and submitted to the network (and in the case of contract related transations simulated first). + +Technically these three are different operations, of which a transaction can contain upto 100 operations. However, in the case of contract related operations a transaction is limited to just one. + +So for all other transactions the CLI provides the `tx` subcommands. These are: + +- `new` +- `sign` +- `send` +- `simulate` + + +## `tx new` + +For the following examples we will use the following accounts: + +```sh +stellar keys generate --fund alice --network testnet +stellar keys generate --no-fund bob +# You can add a public key to the keys +stellar keys add --public-key GCXLHURQS5LX77PBQWEGJLYDPXGVR2F5ME2OPBWQBGJKG2IOBBO2XY5O charlie +## and use testnet +stellar network use testnet +``` + +### Create Account + +Creates and funds a new Stellar account. Above `alice` was funded by friendbot[citation here]. However, +`bob` and `charlie` were not. So we can use the `create-account` command to fund them. + +`bob` will receive 10 XLM and `charlie` will get 1 XLM. + +```sh +stellar tx new create-account \ + --source alice \ + --destination bob \ + --starting-balance 100_000_000 + +stellar tx new create-account \ + --source alice \ + --destination charlie \ + --starting-balance 10_000_000 +``` + +Notes: +- `--starting-balance`: Initial balance in stroops to fund the account with (1 XLM = 10,000,000 stroops) + +### Payment + +`bob` feels bad that `charlie` only got 1 XLM, so they will send 4 more XLM to `charlie`. + +```sh +stellar tx new payment \ + --source bob \ + --destination charlie \ + --asset native \ + --amount 40_000_000 +``` + +Notes: +- `--asset`: The asset to send - either "native" for XLM or "CODE:ISSUER" format for other assets + + +### Bump Sequence + +Bump an account's sequence number forward: + +```sh +stellar tx new bump-sequence \ + --source alice \ + --bump-to 123450 +``` + + +### Account Merge + +Merge one account into another, transferring all XLM. + +`bob` decides to continue spreading the wealth and merges their account into `charlie`'s. + +```sh +stellar tx new account-merge \ + --source bob \ + --account chalrie +``` + +Notes: +- `--source`: The account to remove from the ledger, thus this is its final tranaction + +### Set Trustline Flags + +Modify authorization flags on a trustline: + +```sh +stellar tx new set-trustline-flags \ + --source alice \ + --asset USDC:GCXLHURQS5LX77PBQWEGJLYDPXGVR2F5ME2OPBWQBGJKG2IOBBO2XY5O \ + --trustor charlie \ + --set-authorize \ + --set-authorize-to-maintain-liabilities \ + --set-trustline-clawback-enabled +``` + +Arguments: +- `--source`: The issuing account setting the flags (must be the asset issuer) +- `--asset`: The asset in CODE:ISSUER format +- `--trustor`: The account whose trustline flags to modify +- `--set-authorize`: Enable full authorization +- `--set-authorize-to-maintain-liabilities`: Enable limited authorization +- `--set-trustline-clawback-enabled`: Enable clawback for this trustline +- `--clear-*`: Corresponding clear flags to remove each setting + +### Set Options + +Configure account settings: + +```sh +stellar tx new set-options \ + --source alice \ + --inflation-dest GCXLHURQS5LX77PBQWEGJLYDPXGVR2F5ME2OPBWQBGJKG2IOBBO2XY5O \ + --home-domain "example.com" \ + --master-weight 100 \ + --med-threshold 100 \ + --low-threshold 100 \ + --high-threshold 100 \ + --signer GBXSGN5GX4PZOSBHB4JJF67CEGSGT7DGBGGUGWXI4WOQMQEA4SFV2HTJ \ + --signer-weight 1 \ + --set-required \ + --set-revocable \ + --set-clawback-enabled \ + --set-immutable +``` + +Notes: +- `--source`: Account to modify settings for +- `--inflation-dest`: Set inflation destination account +- `--home-domain`: Set home domain for federation/compliance +- `--master-weight`: Weight of the account's master key (0-255) +- `--low-threshold`: Weight threshold for low security operations +- `--med-threshold`: Weight threshold for medium security operations +- `--high-threshold`: Weight threshold for high security operations +- `--signer`: Add a new signer public key +- `--signer-weight`: Weight for the new signer (0 removes the signer) +- `--set-required`: Enable requiring authorization for new trustlines +- `--set-revocable`: Enable revoking of trustlines +- `--set-clawback-enabled`: Enable clawback for asset issuing account +- `--set-immutable`: Make account settings immutable +- `--clear-*`: Corresponding clear flags to remove each setting + +### Change Trust + +Create or modify a trustline: + +```sh +stellar tx new change-trust \ + --source alice \ + --line USDC:ISSUER \ + --limit 100000000 +``` + +Arguments: +- `--source`: Account creating/modifying the trustline +- `--line`: Asset to create trustline for in CODE:ISSUER format +- `--limit`: Maximum amount that can be held (0 removes trustline) + +### Manage Data + +Manage account data entries: + +```sh +stellar tx new manage-data \ + --source alice \ + --data-name config \ + --data-value 7465737476616c7565 # hex encoded +``` + +Notes: +- `--data-name`: Name of the data entry (up to 64 bytes) +- `--data-value`: Hex encoded value to store (up to 64 bytes, omit to delete) +``` diff --git a/cookbook/tx-op-add.mdx b/cookbook/tx-op-add.mdx new file mode 100644 index 000000000..562fdca0d --- /dev/null +++ b/cookbook/tx-op-add.mdx @@ -0,0 +1,51 @@ +--- +title: `tx op add` +hide_table_of_contents: true +description: Create stellar transactions using the Stellar CLI +--- + +As see before you can use pipes to pass a transaction envolope between commands. Before we have only been looking at transactions with one operation, +however, as mentioned there can be up to 100 operations in a single transaction. + +To add an operation to a transaction you can use the `tx op add` command. This command takes the transaction envolope from the previous command and adds an operation to it. + +Let's consider a more complicated example. Consider issuing an asset, here `USDC` with the requirement that only the issuer can transfer funds to the distrubtor. + +```sh + +stellar keys generate --fund issuer +stellar keys generate --fund distributor + +ISSUER_PK=$(stellar keys address issuer) + +ASSET="USDC:$ISSUER_PK" + +# Issue the asset by setting its options, establishing a trustline, and +# transferring the smallest amount possible to the distributor. Then +# deauthorize the distributor so that people can only send Claimable Balances, +# rather than transferring assets directly. + +# first the issuer sets the options for being able to clawback and revoke the asset +stellar tx new set-options --fee 1000 --source issuer --set-clawback-enabled --set-revocable --build-only \ +# next the distributor establishes a trustline with the asset. Note that here the distributor the source account for the operation, not the issuer +| stellar tx op add change-trust --op-source distributor --line $ASSET \ +# then the issuer sends the smallest amount possible to the distributor +| stellar tx op add payment --destination distributor --asset $ASSET --amount 1 \ +# finally the issuer deauthorizes the distributor from being able to send the asset +| stellar tx op add set-trustline-flags --asset $ASSET --trustor distributor --clear-authorize \ +# Then both accounts need to sign the transaction +| stellar tx sign --sign-with-key issuer \ +| stellar tx sign --sign-with-key distributor \ +| stellar tx send + +# Next is an example of sandwiching an operation. That is giving permission in one operation, preforming the operation, and then removing the permission in a third operation. +# Here is an example of minting new assets to the distributor with a sandwich transaction +# First authorize the distributor to receive the asset +stellar tx new set-trustline-flags --fee 1000 --build-only --source issuer --asset $ASSET --trustor $distributor_PK --set-authorize \ +# Then mint the asset to the distributor +| stellar tx op add payment --destination distributor --asset $ASSET --amount 1_000_000_000_000 \ +# Finally remove the authorization +| stellar tx op add set-trustline-flags --asset $ASSET --trustor distributor --clear-authorize \ +| stellar tx sign --sign-with-key issuer \ +| stellar tx send +``` \ No newline at end of file diff --git a/cookbook/tx-sign.mdx b/cookbook/tx-sign.mdx new file mode 100644 index 000000000..9aa2a9cab --- /dev/null +++ b/cookbook/tx-sign.mdx @@ -0,0 +1,72 @@ +--- +title: `tx sign` and `tx send` +hide_table_of_contents: true +description: Create stellar transactions using the Stellar CLI +--- + +The previous examples of using `tx new` showed how to create transactions. However, these transactions were immediately ready to be signed and submitted to the network. + +To avoid this each of the subcommands has the `--build-only` argument, which as the name suggests only builds the transaction and prints the transaction envolope. + +## `tx sign` + +Let's return to the first example of creating `bob`s account: + + ```sh +stellar tx new create-account \ + --source alice \ + --destination bob \ + --starting-balance 100_000_000 \ + --build-only + ``` + would output something like: + +```sh +AAAAAgAAAADwSUp9CwmVlPN40mKX1I1j39y6DmYc36QS1aK2x6eYVQAAAGQAEcMsAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAACTMkzn1TwPo8SIhnKvnyuv9K2/aWjpX9NTYfyiA7vXaAAAAAAX14QAAAAAAAAAAAA== +``` + +You can inspect it with [stellar lab!](https://lab.stellar.org/xdr/view?$=network$id=testnet&label=Testnet&horizonUrl=https:////horizon-testnet.stellar.org&rpcUrl=https:////soroban-testnet.stellar.org&passphrase=Test%20SDF%20Network%20/;%20September%202015;&xdr$blob=AAAAAgAAAADwSUp9CwmVlPN40mKX1I1j39y6DmYc36QS1aK2x6eYVQAAAGQAEcMsAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAACTMkzn1TwPo8SIhnKvnyuv9K2//aWjpX9NTYfyiA7vXaAAAAAAX14QAAAAAAAAAAAA==;;) Where you can also sign and send the transaction. + +However, you can also sign the transaction with the `tx sign` command. To do this you can pipe the output of the `tx new` command to the `tx sign` command: + +```sh +stellar tx new create-account \ + --source alice \ + --destination bob \ + --starting-balance 100_000_000 \ + --build-only \ + | stellar tx sign --sign-with-key alice +``` + +This should output something like: + +```sh +AAAAAgAAAADwSUp9CwmVlPN40mKX1I1j39y6DmYc36QS1aK2x6eYVQAAAGQAEcMsAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAACTMkzn1TwPo8SIhnKvnyuv9K2/aWjpX9NTYfyiA7vXaAAAAAAX14QAAAAAAAAAAAcenmFUAAABA2FCmaY4U8eFtqzJ1iEowvP1mashskYVxlqPjrM4miH0Q+QrF//A/NWflZPYzR+lySNrjJnRad851+4TbCekICw== +``` +You can again [view it in lab and see that there is now a signature attached to the transaction envolope](AAAAAgAAAADwSUp9CwmVlPN40mKX1I1j39y6DmYc36QS1aK2x6eYVQAAAGQAEcMsAAAAAQAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAACTMkzn1TwPo8SIhnKvnyuv9K2/aWjpX9NTYfyiA7vXaAAAAAAX14QAAAAAAAAAAAcenmFUAAABA2FCmaY4U8eFtqzJ1iEowvP1mashskYVxlqPjrM4miH0Q+QrF//A/NWflZPYzR+lySNrjJnRad851+4TbCekICw==). + +::tip +Or sign with lab! Though currently you must send it from lab and cannot return to the CLI (a work in progress!). +```sh +stellar tx new create-account \ + --source alice \ + --destination bob \ + --starting-balance 100_000_000 \ + --build-only \ + | stellar tx sign --sign-with-lab +``` +::: + +## `tx send` + +Finally, to submit the transaction to the network you can use the `tx send` command. This command will submit the transaction to the network. + +```sh +stellar tx new create-account \ + --source alice \ + --destination bob \ + --starting-balance 100_000_000 \ + --build-only \ + | stellar tx sign --sign-with-key alice \ + | stellar tx send +``` \ No newline at end of file