docs: add examples of using tx new, sign, send, and op add

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)
+```

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
+```

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
+```