Skip to content

treasury-withdrawal-procedure.md

Latest commit

 

History

History
141 lines (88 loc) · 4.81 KB

treasury-withdrawal-procedure.md

File metadata and controls

141 lines (88 loc) · 4.81 KB
Raw

Treasury Withdrawal Action Procedure

Here we intend to document the script and steps within to build a new Treasury Withdrawal governance action.

Note: These scripts and tutorial are only setup for Treasury Withdrawals with a single withdrawal address and amount

Steps

1. Author new metadata via Google Docs

Using the Google Docs template:

2. Export markdown file

Export your metadata from Google Docs as markdown file (.md).

3. Set environment variables

Set secrets, you can use the .env file for this.

source ./scripts/.env

Set some useful variables that we can reuse

export DEPOSIT_RETURN_ADDR="my-address"

export WITHDRAWAL_ADDR="my-address"

Make sure that CARDANO_NODE_NETWORK_ID and CARDANO_NODE_SOCKET_PATH are set.

4. Create the metadata document

Convert the .md to intersect's metadata standard (this is a modified CIP-108 document).

With the metadata-create script taking the data from the doc and creating a .jsonld.

The input file must be a .md file structured with H2 headers (## Title, ## Abstract, ## Motivation, ## Rationale, ## References, ## Authors). Pass --language <BCP-47-tag> to override the default en in the generated @context.@language.

./scripts/metadata-create.sh my-metadata.md --governance-action-type treasury --deposit-return-addr $DEPOSIT_RETURN_ADDR

5. Sanity check the metadata

Generate a markdown representation from the created .jsonld and manually compare against the original .md.

./scripts/cip-108-markdown.sh my-metadata.jsonld

6. Validate the metadata

We can then run our validation script to check

  • compliance with CIP schema(s)
  • compliance with Intersect schemas
  • spell check on CIP108 sections (aspell personal dictionary fetched from the main branch of this repo at runtime; skip with --no-spell-check)
  • URI reachability for every uri/url field plus markdown links and bare URLs inside prose fields; ipfs://<cid> is resolved via $IPFS_GATEWAY_URI (fallback https://ipfs.io). Skip with --no-check-links.
  • body.title length ≤ 80 and body.abstract length ≤ 2500 characters Because the metadata at this point in the procedure has not yet been signed, run with --draft:
./scripts/metadata-validate.sh my-metadata.jsonld --cip108 --cip169 --draft

At least one schema flag (--cipNNN, --intersect-schema, or --schema <URL>) is required.

The --draft flag is what suppresses the "missing author" failure at this stage; it must be omitted in step 9 below so the strict post-signing pass actually catches an empty-authors regression.

7. Add author witness(es)

If metadata passes all the above validations. We can sign it with author key(s).

You can either pass the my-metadata.jsonld to authors to sign, using something like ./scripts/author-create.sh. Or you can run ./scripts/metadata-canonize.sh and share the canonized body hash to sign via standard cardano wallets.

8. Verify the author's witness(es)

Check the author witnesses were added correctly.

./scripts/author-validate.sh my-metadata.jsonld

Pass --no-intersect to skip the comparison against Intersect's well-known author public key.

9. Final validation

Just to double check that all is good now, with author.

  • compliance with CIP schema(s)
  • compliance with Intersect schemas
  • spell check (skip with --no-spell-check)
  • URI reachability (skip with --no-check-links)
  • body.title length ≤ 80 and body.abstract length ≤ 2500 characters
  • structural integrity (non-empty authors)

Run without --draft so the empty-authors check is strict — this is what guarantees the document was actually signed in step 7:

./scripts/metadata-validate.sh my-metadata.jsonld --cip108 --cip169

10. Host on IPFS

Pin the metadata to different IPFS pinning services.

./scripts/ipfs-pin.sh my-metadata.jsonld

To skip a specific pinning service use --no-local, --no-pinata, --no-blockfrost, or --no-nmkr.

11. Verify IPFS hosting

This will now additionally check that the file is accessible via IPFS.

./scripts/ipfs-check.sh my-metadata.jsonld

12. Create the action file

Now we can create an treasury withdrawal governance action file from our metadata.

./scripts/action-create-tw.sh my-metadata.jsonld --deposit-return-addr $DEPOSIT_RETURN_ADDR --withdrawal-addr $WITHDRAWAL_ADDR

13. Submit on testnet

It is highly recommended to submit all actions on testnets before mainnet. This gives the author the opportunity to ensure all explorers pick up and render the action's metadata properly