diff --git a/README.md b/README.md index d353a2e..da7e056 100644 --- a/README.md +++ b/README.md @@ -8,10 +8,16 @@ 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 +#### 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) @@ -20,11 +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-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 + - Applies a spell check to CIP108 metadata fields #### CIP-108 Scripts @@ -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). diff --git a/docs/2025-budget-withdrawals.md b/docs/2025-budget-withdrawals.md index 93aaf7d..7f72028 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,74 +7,153 @@ 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 my-metadata.jsonld +``` + +### 5. Budget specific tests to validate the metadata + +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 -- lets look over and make sure we are happy +```shell +./scripts/budget-metadata-validate.sh my-metadata.jsonld +``` -### 4. Sign with author's key +### 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 my-metadata.jsonld intersect-key.skey ``` -Copy the authored one back. +### 7. Verify the author's witness -### 5. Verify the witnesses +Check the author witness. -Check the author witnesses. +Ensure it is from the expected intersect key. ```shell -./scripts/verify-author-witness.sh +./scripts/author-validate.sh my-metadata.jsonld ``` -### 6. Host on IPFS +### 8. Host on IPFS -Host the author witnessed metadata on IPFS. +Pin the metadata to different IPFS pinning services. + +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 ``` -### 7. Create the action files +### 9. Check metadata is accessible via IPFS -todo +Hit a couple of gateways and see if it is accessible. -### 8. Check action files +```shell +./scripts/ipfs-check.sh my-metadata.jsonld +``` -todo +### 10. Create the action file + +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 +``` -### 9. Build the transactions +### 13. Build the transaction todo -### 10. check the transactions +### . check the transactions todo \ No newline at end of file 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}" diff --git a/scripts/budget-check-metadata.sh b/scripts/budget-metadata-validate.sh similarity index 77% rename from scripts/budget-check-metadata.sh rename to scripts/budget-metadata-validate.sh index 902d8a1..3b68f21 100755 --- a/scripts/budget-check-metadata.sh +++ b/scripts/budget-metadata-validate.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."