Merge pull request #40 from IntersectMBO/tweak-docs

update docs

Author: Ryun1

README.md

@@ -23,7 +23,7 @@ This repository holds shell scripts that Intersect uses to engage in Cardano on-
 - [ipfs-check.sh](./scripts/ipfs-check.sh)
   - Checks if a file is accessible via free IPFS gateways
 - [ipfs-pin.sh](./scripts/ipfs-pin.sh)
-  - Allows user to pin a file on a number of pinning services
+  - Allows user to pin JSONLD file(s) on a number of pinning services
   - Optionally allows the user to check file's discoverability first
 
 #### Governance (CIP-100+) Metadata Scripts

docs/2025-budget-withdrawals.md

@@ -11,11 +11,11 @@ This is done via Google docs.
 
 ### 1. Download `.docx` into working directory
 
-For Intersect [governance-actions](https://github.com/IntersectMBO/governance-actions) will be used as working directory.
+For Intersect [governance-actions](https://github.com/IntersectMBO/governance-actions) will be used as a working directory.
 
 ### 2. Set environment variables
 
-Set secrets
+Set secrets, you can use the `.env` file for this.
 
 ```shell
 source ./scripts/.env
@@ -26,17 +26,13 @@ Set some useful variables
 ```shell
 export DEPOSIT_RETURN_ADDR="stake1uyvjdz9rxsfsmv44rtk75k2rqyqskrga96dgdfrqjvjjpwsefcjnp"
 export WITHDRAWAL_ADDR="stake17xzc8pt7fgf0lc0x7eq6z7z6puhsxmzktna7dluahrj6g6ghh5qjr"
-
-export a="../governance-actions/mainnet/2025-07-13-budget-2025"
 ```
 
 Make sure that `CARDANO_NODE_NETWORK_ID` and `CARDANO_NODE_SOCKET_PATH` are set.
 
-
 ### 3. Create the metadata documents
 
-Convert the `.docx` to [intersect's metadata standard](https://github.com/IntersectMBO/governance-actions/tree/main/schemas)
-this is a modified CIP-108 document.
+Convert the `.docx` to [intersect's metadata standard](https://github.com/IntersectMBO/governance-actions/tree/main/schemas) (this is a modified CIP-108 document).
 
 With the `metadata-create` script taking the data from the doc and creating a `.jsonld`.
 
@@ -76,8 +72,10 @@ We will pass `--no-author` as we know there is no author witness yet.
 
 We will pass `--no-ipfs` as we know we didn't put it on ipfs yet.
 
+We will also pass in our known deposit address and withdrawal address.
+
 ```shell
-./scripts/budget-metadata-validate.sh $a/EC --no-author --no-ipfs --deposit-return-addr $DEPOSIT_RETURN_ADDR --withdrawal-addr $WITHDRAWAL_ADDR
+./scripts/budget-metadata-validate.sh ./my-metadata-directory --no-author --no-ipfs --deposit-return-addr $DEPOSIT_RETURN_ADDR --withdrawal-addr $WITHDRAWAL_ADDR
 ```
 
 ### 6. Sign with author's key
@@ -88,7 +86,7 @@ Sign it with the Intersect author key
 (this will be done via an air-gapped setup)
 
 ```shell
-./scripts/author-create.sh ./my-metadata-directory intersect-key.skey
+./scripts/author-create.sh ./my-metadata-directory intersect-key.skey --author-name "Intersect"
 ```
 
 ### 7. Verify the author's witness
@@ -112,13 +110,23 @@ Pin the metadata to different IPFS pinning services.
 ./scripts/ipfs-pin.sh ./my-metadata-directory
 ```
 
-### 9. Create the action file
+### 9. Verify IPFS hosting
+
+We can use `budget-metadata-validate.sh` now without the `--no-ipfs` flag
+
+This will now additionally check that the file is accessible via IPFS and that all the references (if they are using IPFS) are also accessible.
+
+```shell
+./scripts/budget-metadata-validate.sh ./my-metadata-directory --deposit-return-addr $DEPOSIT_RETURN_ADDR --withdrawal-addr $WITHDRAWAL_ADDR
+```
+
+### 10. Create the action file
 
 Now we can create a governance action file from our metadata.
 
 This performs some validations
 - can check against some known deposit return and withdrawal address
-- checks that metadata fields are present and look right
+- checks that metadata fields are present
 - compares the addresses against the local node
 - checks if withdrawal address is script-based
 - checks if withdrawal address and deposit address are registered
@@ -130,12 +138,13 @@ This performs some validations
 ./scripts/action-create-tw.sh my-metadata.jsonld --withdraw-to-script --deposit-return-addr $DEPOSIT_RETURN_ADDR --withdrawal-addr $WITHDRAWAL_ADDR
 ```
 
-### 10. Share the action file
+### 11. Share the action file
 
 Share the action file and the `.action.json` representation publicly.
 
 Have people check that this looks good.
-You **don't** want to mess this up.
+
+You **don not** want to mess this up!
 
 Checks;
 - withdrawal and stake address are correct
@@ -144,27 +153,16 @@ Checks;
 - metadata compliance with .docx
 - hash and URI match
 
-### 11. Check action file
+### 12. Submit test actions to testnets
 
-Automated checks.
+Manually submit the action to other networks.
 
-Checks;
-- withdrawal and stake address are correct
-- withdrawal address is script-based
-- withdrawal amount is correct -- can auto-check against title
-- metadata accessible via IPFS
-- metadata compliance with .docx
-- hash and URI match
-- manually have the user confirm aspects too
-
-```shell
-./scripts/action-validate.sh my-metadata.action --withdraw-to-script --deposit-return-addr $DEPOSIT_RETURN_ADDR --withdrawal-addr $WITHDRAWAL_ADDR
-```
+We want to check that the metadata is picked up properly.
 
-### 13. Build the transaction
+### 13. Build the mainnet transaction
 
 Manually, dependent on where the deposit is from.
 
-### 14. check the transactions
+### 14. Check the transactions
 
-Manually.
+Manually, review and double check all key details.