From 3f25b1f5ea9daee99ac348074503bbeac197ca94 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 11 Jul 2025 09:58:06 +0100 Subject: [PATCH 1/5] fix budget check --- scripts/budget-check-metadata.sh | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/scripts/budget-check-metadata.sh b/scripts/budget-check-metadata.sh index 902d8a1..3b68f21 100755 --- a/scripts/budget-check-metadata.sh +++ b/scripts/budget-check-metadata.sh @@ -17,7 +17,6 @@ usage() { echo " " echo "Options:" echo " Path to your CIP108 file or directory." - echo " --no-author Don't run checks for author witnesses (default: $AUTHOR_CHECK)" exit 1 } @@ -28,10 +27,6 @@ check_author="$AUTHOR_CHECK" # Parse command line arguments while [[ $# -gt 0 ]]; do case $1 in - --no-author) - check_author="false" - shift - ;; -h|--help) usage ;; @@ -62,21 +57,11 @@ if [ -d "$input_path" ]; then echo "Author witnesses will be checked..." echo " " echo "Running validation $file" - ./scripts/cip-108-validate.sh "$file" + ./scripts/metadata-validate.sh "$file" --intersect-budget echo " " echo "Checking author for $file" ./scripts/author-verify-witness.sh "$file" echo " " - - # todo add more checks here - else - echo "Skipping author witness checks..." - echo " " - echo "Running validation $file" - ./scripts/validate-cip-108.sh "$file" - echo " " - - # todo add more checks here fi else echo "Error: '$file' is not a valid file." From b3df36380cc5e74b5935b9cc34e7cabaabc82f5c Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 11 Jul 2025 10:30:13 +0100 Subject: [PATCH 2/5] rename budget validate --- README.md | 2 +- .../{budget-check-metadata.sh => budget-metadata-validate.sh} | 0 2 files changed, 1 insertion(+), 1 deletion(-) rename scripts/{budget-check-metadata.sh => budget-metadata-validate.sh} (100%) diff --git a/README.md b/README.md index d353a2e..2408f85 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ This repository holds shell scripts that Intersect uses to engage in Cardano on- #### 2025 Budget Scripts -- [budget-check-metadata.sh](./scripts/budget-check-metadata.sh) +- [budget-metadata-validate.sh](./scripts/budget-metadata-validate.sh) - Runs correctness and validity checks for budget treasury withdrawal CIP108 metadata. - Uses a combination of the other scripts diff --git a/scripts/budget-check-metadata.sh b/scripts/budget-metadata-validate.sh similarity index 100% rename from scripts/budget-check-metadata.sh rename to scripts/budget-metadata-validate.sh From f530c9e12532960f762185855427beaab576561f Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 11 Jul 2025 11:34:28 +0100 Subject: [PATCH 3/5] update base readme --- README.md | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 2408f85..35ceada 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,12 @@ This repository holds shell scripts that Intersect uses to engage in Cardano on- - Runs correctness and validity checks for budget treasury withdrawal CIP108 metadata. - Uses a combination of the other scripts +#### Governance Action Scripts + +- [action-create-tw.sh](./scripts/action-create-tw.sh) + - Creates a treasury withdrawal governance action from a Intersect metadata + - Uses a local cardano node socket file + #### IPFS Scripts - [ipfs-check.sh](./scripts/ipfs-check.sh) @@ -22,7 +28,9 @@ This repository holds shell scripts that Intersect uses to engage in Cardano on- #### CIP-100+ Metadata Scripts -- [metadata-validate.sh](./scripts/cip-108-validate.sh) +- [metadata-create.sh](./scripts/metadata-create.sh) + - Creates Intersect budget metadata file from a `.docx` +- [metadata-validate.sh](./scripts/metadata-validate.sh) - Compares governance metadata against the established schema(s) - Applies a spell check to CIP108 metadata @@ -43,7 +51,7 @@ This repository holds shell scripts that Intersect uses to engage in Cardano on- - [hash.sh](./scripts/hash.sh) - Performs a blake2b-256 hash on provided file - [pdf-remove-metadata.sh](./scripts/pdf-remove-metadata.sh) - - Removes PDF metadata from PDF files + - Removes PDF metadata from PDF files ### Documentation @@ -62,12 +70,29 @@ In order to run all of these scripts you will need - [ipfs](https://docs.ipfs.eth.link/install/command-line/) - jq -## Secrets +probably more I have missed... -Secrets can be stored via `./scripts/.env` and based on `./scripts/.env.example`. +## Environment Variables + +### Cardano Node + +The only script that uses secrets is `action-create-tw.sh`. + +This expects `CARDANO_NODE_NETWORK_ID` and `CARDANO_NODE_SOCKET_PATH` to be set. +So you'll need a local cardano node socket path. + +### Secrets The only script that uses secrets is `ipfs-pin.sh`. +Secrets can be stored via `./scripts/.env` and based on `./scripts/.env.example`. + +This is setup so you can run: + +```shell +source ./scripts/.env +``` + ## License See [License](./LICENSE). From da4ef2d460584d7df390652195071673f5ed11ef Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 11 Jul 2025 12:15:19 +0100 Subject: [PATCH 4/5] improve the docs --- README.md | 4 +- docs/2025-budget-withdrawals.md | 74 +++++++++++++++++++++------------ 2 files changed, 50 insertions(+), 28 deletions(-) diff --git a/README.md b/README.md index 35ceada..da7e056 100644 --- a/README.md +++ b/README.md @@ -26,13 +26,13 @@ This repository holds shell scripts that Intersect uses to engage in Cardano on- - Allows user to pin a file on a number of pinning services - Optionally allows the user to check file's discoverability first -#### CIP-100+ Metadata Scripts +#### Governance (CIP-100+) Metadata Scripts - [metadata-create.sh](./scripts/metadata-create.sh) - Creates Intersect budget metadata file from a `.docx` - [metadata-validate.sh](./scripts/metadata-validate.sh) - Compares governance metadata against the established schema(s) - - Applies a spell check to CIP108 metadata + - Applies a spell check to CIP108 metadata fields #### CIP-108 Scripts diff --git a/docs/2025-budget-withdrawals.md b/docs/2025-budget-withdrawals.md index 93aaf7d..081cb5c 100644 --- a/docs/2025-budget-withdrawals.md +++ b/docs/2025-budget-withdrawals.md @@ -1,4 +1,4 @@ -# Draft -- Intersect 2025 Budget Treasury Withdrawals +# Intersect 2025 Budget Treasury Withdrawals Here we intend to document the scripts used within the technical processes of building and verifying the treasury withdrawal actions. @@ -7,47 +7,69 @@ Here we intend to document the scripts used within the technical processes of bu ### Pre-Requisites Have authored your treasury withdrawal metadata. -This can be done via Google docs, or some collaborative document platform. +This is done via Google docs. -### 1. Create the metadata documents +### 1. Download `.docx` into working directory -convert the Google docs to .JSONLD +For Intersect [governance-actions](https://github.com/IntersectMBO/governance-actions) will be used as working directory. -tbd how to do this and tbd how much can be automated +### 2. Create the metadata documents -### 2. Check 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. -Ensure that the metadata documents are correct. +With the `metadata-create` script taking the data from the doc and creating a `.jsonld`. + +```shell +./scripts/metadata-create.sh my-metadata.docx +``` + +### 3. Sanity check the metadata + +Generate a markdown representation from the created `.jsonld` +and manually compare against the `.docx`. ```shell -./scripts/validate-budget-metadata.sh +./scripts/cip-108-create-human-readable.sh my-metadata.jsonld ``` -automated checks -- compliance with CIPs -- check on IPFS ? -- compliance with budget schema +### 4. Formally validate the metadata + +Ensure that the metadata documents are correct. + +automated checks: +- compliance with CIP schema(s) +- compliance with Intersect schema - spelling check -- probably more -### 3. Manual check +```shell +./scripts/metadata-validate.sh +``` + +### 5. Budget specific tests to validate the metadata -- lets look over and make sure we are happy +Then do specific budget checks: +- is author valid? +- expected withdrawal and deposit address? +- addresses are key-based or script-based? +- manually confirm the withdrawal amount -### 4. Sign with author's key +```shell +./scripts/budget-metadata-validate.sh +``` + +### 6. Sign with author's key If metadata passes all the checks. Sign it with the Intersect author key -using script +(this will be done via an air-gapped setup) ```shell -./scripts/create-author-witness.sh +./scripts/author-create.sh ``` -Copy the authored one back. - -### 5. Verify the witnesses +### 6. Verify the witnesses Check the author witnesses. @@ -55,7 +77,7 @@ Check the author witnesses. ./scripts/verify-author-witness.sh ``` -### 6. Host on IPFS +### . Host on IPFS Host the author witnessed metadata on IPFS. @@ -63,18 +85,18 @@ Host the author witnessed metadata on IPFS. ./scripts/ipfs.sh ``` -### 7. Create the action files +### . Create the action files todo -### 8. Check action files +### . Check action files todo -### 9. Build the transactions +### . Build the transactions todo -### 10. check the transactions +### . check the transactions todo \ No newline at end of file From c273856971f5b3cfbd8a6038519a3d1b73fecd39 Mon Sep 17 00:00:00 2001 From: Ryan Williams Date: Fri, 11 Jul 2025 12:34:32 +0100 Subject: [PATCH 5/5] flesh out docs --- docs/2025-budget-withdrawals.md | 85 +++++++++++++++++++++++++++------ scripts/action-create-tw.sh | 2 + 2 files changed, 73 insertions(+), 14 deletions(-) diff --git a/docs/2025-budget-withdrawals.md b/docs/2025-budget-withdrawals.md index 081cb5c..7f72028 100644 --- a/docs/2025-budget-withdrawals.md +++ b/docs/2025-budget-withdrawals.md @@ -43,7 +43,7 @@ automated checks: - spelling check ```shell -./scripts/metadata-validate.sh +./scripts/metadata-validate.sh my-metadata.jsonld ``` ### 5. Budget specific tests to validate the metadata @@ -55,7 +55,7 @@ Then do specific budget checks: - manually confirm the withdrawal amount ```shell -./scripts/budget-metadata-validate.sh +./scripts/budget-metadata-validate.sh my-metadata.jsonld ``` ### 6. Sign with author's key @@ -66,34 +66,91 @@ Sign it with the Intersect author key (this will be done via an air-gapped setup) ```shell -./scripts/author-create.sh +./scripts/author-create.sh my-metadata.jsonld intersect-key.skey ``` -### 6. Verify the witnesses +### 7. Verify the author's witness -Check the author witnesses. +Check the author witness. + +Ensure it is from the expected intersect key. ```shell -./scripts/verify-author-witness.sh +./scripts/author-validate.sh my-metadata.jsonld ``` -### . Host on IPFS +### 8. Host on IPFS + +Pin the metadata to different IPFS pinning services. -Host the author witnessed metadata on IPFS. +You'll need to set the secrets for these pinning services first. ```shell -./scripts/ipfs.sh +source ./scripts/.env + +./scripts/ipfs-pin.sh my-metadata.jsonld ``` -### . Create the action files +### 9. Check metadata is accessible via IPFS -todo +Hit a couple of gateways and see if it is accessible. + +```shell +./scripts/ipfs-check.sh my-metadata.jsonld +``` -### . Check action files +### 10. Create the action file -todo +Now we can create a governance action file from our metadata. + +This does require `CARDANO_NODE_NETWORK_ID` and `CARDANO_NODE_SOCKET_PATH` to be set. + +This performs some validations +- can check against some known deposit return and withdrawal address +- checks that metadata fields are present and look right +- compares the addresses against the local node +- checks if withdrawal address is script-based +- checks if withdrawal address and deposit address are registered +- checks if withdrawal address is not vote delegated or is delegated to auto-abstain +- checks that the metadata is hosted on ipfs +- has user manually confirm the addresses and the amount + +```shell +./scripts/ipfs-check.sh my-metadata.jsonld --withdraw-to-script --deposit-return-addr --withdrawal-addr +``` + +### 11. Share the action file + +Share the action file and the .json representation publicly. + +Have people check that this looks good. +You dont want to mess this up. + +Checks; +- withdrawal and stake address are correct +- withdrawal address is script-based +- withdrawal amount is correct +- metadata compliance with .docx +- hash and URI match + +### 12. Check action file + +Automated checks. + +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-action.action +``` -### . Build the transactions +### 13. Build the transaction todo diff --git a/scripts/action-create-tw.sh b/scripts/action-create-tw.sh index a6227fe..2fa3edb 100755 --- a/scripts/action-create-tw.sh +++ b/scripts/action-create-tw.sh @@ -317,6 +317,8 @@ else exit 1 fi +# todo add check if withdrawal address is delegated to an SPO + echo -e "${GREEN}Automatic validations passed${NC}" echo -e " " echo -e "${CYAN}Computing details${NC}"