Merge plutus 1.47.0.0

.github/workflows/code-coverage-report.yml

@@ -25,9 +25,22 @@ jobs:
         run: | 
           nix build --no-warn-dirty --accept-flake-config .#project-coverage-report
 
+      # Note: Only the Union Report is required (found in the 'all' subdirectory).
+      # We intentionally exclude the Individual Reports due to their large size, 
+      # which makes them impossible to upload to GitHub Pages; Jekyll fails with 
+      # an out of disk error:
+      # https://github.com/IntersectMBO/plutus/actions/runs/15466656160/job/43540218892)
+      # As of June 2025, the full set of Individual Reports occupies approximately 3.1 GB, 
+      # with plutus-metatheory alone accounting for ~3 GB.
+      - name: Patch Report
+        run: | 
+          mkdir -p out
+          cp -Lr result/share/hpc/vanilla/html/all/* out
+          mv out/hpc_index.html out/index.html
+
       - name: Deploy Report
         uses: JamesIves/github-pages-deploy-action@v4.7.3
         with:
-          folder: result/share/hpc/vanilla/html
+          folder: out
           target-folder: dev/coverage
           single-commit: true

.github/workflows/docusaurus-site.yml

@@ -1,7 +1,9 @@
 # This workflow builds and deploys the Docusaurus site.
 # 
-# This workflow builds the site on pull requests, and it also automatically deploys 
-# the site on push to master or on workflow dispatch to: 
+# On pull requests, this workflow builds the site and deploys a temporary preview
+# to gh-pages.
+#
+# On push to master or on workflow dispatch it deploys the site to: 
 # https://plutus.cardano.intersectmbo.org/docs
 
 
@@ -20,6 +22,7 @@ jobs:
     runs-on: [self-hosted, plutus-ci]
     permissions:
       contents: write
+      pull-requests: write
     environment:
       name: github-pages
     steps:
@@ -30,6 +33,12 @@ jobs:
         working-directory: doc/docusaurus
         run: nix develop --no-warn-dirty --accept-flake-config --command bash -c 'yarn && yarn build'
 
+      - name: Deploy Preview
+        if: github.event_name == 'pull_request' && github.event.action != 'closed'
+        uses: rossjrw/pr-preview-action@v1
+        with:
+          source-dir: doc/docusaurus/build
+
       - name: Deploy Site 
         if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
         uses: JamesIves/github-pages-deploy-action@v4.7.3

.github/workflows/metatheory-site.yml

@@ -1,10 +1,3 @@
-# This workflow builds and publishes the Metatheory site to:
-# https://plutus.cardano.intersectmbo.org/metatheory/$version
-# And optionally to:
-# https://plutus.cardano.intersectmbo.org/metatheory/latest
-# On push to master, this workflows publishes to:
-# https://plutus.cardano.intersectmbo.org/metatheory/master
-
 # This workflow builds and deploys the Metatheory site.
 # 
 # When this workflow is triggered manually via workflow dispatch, it builds and then 

.github/workflows/slack-message-broker.yml

@@ -20,8 +20,8 @@ on:
       - "🔮 Metatheory Site"
       - "🌘 Nightly Testsuite"
       - "📝 Papers & Specs"
-      - "🏛️ Plinth Template"
       - "📊 Code Coverage Report"
+      - "pages-build-deployment"
 
 jobs:
   Send:

SECURITY.md

@@ -15,4 +15,5 @@ Please provide a clear and concise description of the vulnerability, including:
 If you have developed any code or utilities that can help demonstrate the suspected
 vulnerability, please mention them in your email but ***DO NOT*** attempt to include them as
 attachments as this may cause your Email to be blocked by spam filters.
-See the security file in the [Cardano engineering handbook](https://github.com/input-output-hk/cardano-engineering-handbook/blob/main/SECURITY.md).
+See the security file in the [Cardano engineering handbook](https://github.com/input-output-hk/cardano-engineering-handbook/blob/main/SECURITY.md).
+

cardano-constitution/cardano-constitution.cabal

@@ -1,6 +1,6 @@
 cabal-version:      3.0
 name:               cardano-constitution
-version:            1.46.0.0
+version:            1.47.0.0
 license:            Apache-2.0
 license-files:
   LICENSE
@@ -86,10 +86,10 @@ library
     , base               >=4.9   && <5
     , containers
     , filepath
-    , plutus-core        ^>=1.46
-    , plutus-ledger-api  ^>=1.46
-    , plutus-tx          ^>=1.46
-    , plutus-tx-plugin   ^>=1.46
+    , plutus-core        ^>=1.47
+    , plutus-ledger-api  ^>=1.47
+    , plutus-tx          ^>=1.47
+    , plutus-tx-plugin   ^>=1.47
     , regex-tdfa
     , safe
     , template-haskell
@@ -132,10 +132,10 @@ test-suite cardano-constitution-test
     , containers
     , directory
     , filepath
-    , plutus-core                      ^>=1.46
+    , plutus-core                      ^>=1.47
     , plutus-core:plutus-core-testlib
-    , plutus-ledger-api                ^>=1.46
-    , plutus-tx                        ^>=1.46
+    , plutus-ledger-api                ^>=1.47
+    , plutus-tx                        ^>=1.47
     , QuickCheck
     , serialise
     , tasty
@@ -160,4 +160,4 @@ executable create-json-envelope
     , base
     , cardano-api
     , cardano-constitution
-    , plutus-ledger-api     ^>=1.46
+    , plutus-ledger-api     ^>=1.47

doc/docusaurus/docs/using-plinth/special-functions-and-types.md

@@ -41,8 +41,111 @@ Note that in regular Haskell, `&&` and `||` are _not_ special, as Haskell suppor
 
 [`IsString`](https://hackage.haskell.org/package/base/docs/Data-String.html#t:IsString) is a type class from `base`, and can be used along with the `OverloadedStrings` language extension to convert string literals to types other than `String`.
 
-Most `IsString` instances are unsupported by the Plinth compiler, other than a few special cases.
-At present, it provides support for `BuiltinString` and `BuiltinByteString`, with the caveat that the `fromString` method must be applied to a string literal.
-
-As previously noted, `String` and `ByteString` are not available in Plinth, so you'll need to use `BuiltinString` or `BulitinByteString`.
-This lets you write `"hello" :: BuiltinString` and `"world" :: BuiltinByteString` in Plinth, which is quite convenient.
+> :pushpin: **NOTE**
+>
+> `String` and `ByteString` are not available in Plinth, so you'll need to use `BuiltinString` or `BuiltinByteString`.
+
+This lets you write `"hello" :: BuiltinString` in Plinth, which is quite convenient.
+
+### Builtin ByteString literals
+
+Working with `BuiltinByteString` using `OverloadedStrings` requires care. For backward compatibility, an `IsString` instance exists for `BuiltinByteString`. This instance mirrors the standard Haskell `IsString ByteString` behavior: it converts each character to a byte by taking the lowest 8 bits of its Unicode code point.
+
+However, its use is discouraged because this conversion is lossy, keeping only the lowest byte of each character's Unicode code point. This means that characters with Unicode code points above 255 (i.e., outside the Latin-1 range) will not be represented correctly, leading to potential data loss. The example below illustrates this truncation.
+
+<details>
+<summary>Example of lossy conversion</summary>
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+
+import qualified Data.ByteString as BS
+import Data.Char (ord)
+import Data.Bits ((.&.))
+
+main = do
+  print $ BS.unpack ("世" :: BS.ByteString)  -- [22]
+  print $ ord '世'                           -- 19990
+  print $ (19990 :: Integer) .&. 0xFF        -- 22 (truncation result)
+```
+</details>
+
+Instead, Plinth provides encoding-specific newtypes, each with its own `IsString` instance. Currently, two encodings are supported:
+- **Hexadecimal**, also known as **Base 16**, via the `BuiltinByteStringHex` newtype.
+- **UTF-8** via the `BuiltinByteStringUtf8` newtype.
+
+The newtypes are zero-cost abstractions that tell the compiler which `IsString` instance to use.
+They can be converted to `BuiltinByteString` using the corresponding functions:
+
+```haskell
+unBuiltinByteStringHex :: BuiltinByteStringHex -> BuiltinByteString
+unBuiltinByteStringUtf8 :: BuiltinByteStringUtf8 -> BuiltinByteString
+```
+
+Here are some usage examples:
+```haskell
+{-# LANGUAGE OverloadedStrings #-}
+
+import PlutusTx.Builtins 
+  ( BuiltinByteString
+  , BuiltinByteStringUtf8
+  , unBuiltinByteStringHex
+  , unBuiltinByteStringUtf8
+  )
+
+aceOfBase16 :: BuiltinByteString
+aceOfBase16 = unBuiltinByteStringHex "ACE0FBA5E"
+-- ^ type inference figures out that the literal has 
+-- the `BuiltinByteStringHex` type
+
+nonLatinTokenName :: BuiltinByteString
+nonLatinTokenName = 
+  unBuiltinByteStringUtf8 
+    ("Мой Клёвый Токен" :: BuiltinByteStringUtf8)
+-- here we use an explicit ^^^ type annotation for the
+-- `BuiltinByteStringUtf8` newtype 
+```
+
+:::tip
+You do not need to convert a `BuiltinByteStringHex` or `BuiltinByteStringUtf8` value to `BuiltinByteString` immediately.
+You can pass it around and only convert it when the context requires a `BuiltinByteString`.
+This preserves the encoding information in the type and allows downstream code to rule out invalid states.
+For example:
+```haskell
+hexBytes :: BuiltinByteStringHex
+hexBytes = "AABBCCDD" 
+
+numberOfBytes :: BuiltinByteStringHex -> Integer
+numberOfBytes hex = lengthOfByteString (unBuiltinByteStringHex hex)
+```
+:::
+
+As an alternative to the `OverloadedStrings` language extension, you can use special functions from the `PlutusTx.Builtins.HasOpaque` module:
+
+```haskell 
+import PlutusTx.Builtins.HasOpaque 
+  ( stringToBuiltinByteStringHex
+  , stringToBuiltinByteStringUtf8
+  )
+
+-- stringToBuiltinByteStringHex :: String -> BuiltinByteString
+
+aceOfBase16 :: BuiltinByteString
+aceOfBase16 = stringToBuiltinByteStringHex "ACE0FBA5E" 
+
+-- stringToBuiltinByteStringUtf8 :: String -> BuiltinByteString
+
+mother :: BuiltinByteString
+mother = stringToBuiltinByteStringUtf8 "Мама"
+```
+
+These functions convert Haskell's `String` literal to Plinth's `BuiltinByteString` using the corresponding encoding.
+What makes them special is that they are executed by Plinth **at compile time**, without increasing the size and execution budget of a Plinth program.
+
+:::caution
+These compile-time functions need to be *syntactically* applied to string literals, meaning that you cannot apply them to variables or expressions that are not string literals.
+For example, the following code will not compile:
+
+```haskell
+stringToBuiltinByteStringHex ("ACE0F" ++ "BA5E")
+```
+:::

doc/docusaurus/docusaurus-examples.cabal

@@ -40,10 +40,10 @@ library docusaurus-code
 
   build-depends:
     , base               >=4.9   && <5
-    , plutus-core        ^>=1.46
-    , plutus-ledger-api  ^>=1.46
-    , plutus-tx          ^>=1.46
-    , plutus-tx-plugin   ^>=1.46
+    , plutus-core        ^>=1.47
+    , plutus-ledger-api  ^>=1.47
+    , plutus-tx          ^>=1.47
+    , plutus-tx-plugin   ^>=1.47
 
 executable example-cip57
   import:           lang, ghc-version-support, os-support
@@ -54,9 +54,9 @@ executable example-cip57
   build-depends:
     , base               ^>=4.18
     , containers
-    , plutus-ledger-api  ^>=1.46
-    , plutus-tx          ^>=1.46
-    , plutus-tx-plugin   ^>=1.46
+    , plutus-ledger-api  ^>=1.47
+    , plutus-tx          ^>=1.47
+    , plutus-tx-plugin   ^>=1.47
 
 executable example-evaluation
   import:           lang, ghc-version-support, os-support
@@ -66,9 +66,9 @@ executable example-evaluation
   other-modules:    Paths_docusaurus_examples
   build-depends:
     , base                         ^>=4.18
-    , plutus-ledger-api            ^>=1.46
-    , plutus-tx                    ^>=1.46
-    , plutus-tx-plugin             ^>=1.46
+    , plutus-ledger-api            ^>=1.47
+    , plutus-tx                    ^>=1.47
+    , plutus-tx-plugin             ^>=1.47
     , plutus-tx:plutus-tx-testlib
     , text
 
@@ -88,6 +88,6 @@ executable quickstart
     , base               >=4.9   && <5
     , base16-bytestring
     , bytestring
-    , plutus-ledger-api  ^>=1.46
-    , plutus-tx          ^>=1.46
-    , plutus-tx-plugin   ^>=1.46
+    , plutus-ledger-api  ^>=1.47
+    , plutus-tx          ^>=1.47
+    , plutus-tx-plugin   ^>=1.47

doc/docusaurus/package.json

@@ -42,7 +42,8 @@
     "@babel/helpers": "7.26.10",
     "image-size": "1.2.1",
     "estree-util-value-to-estree": "3.3.3",
-    "http-proxy-middleware": "2.0.9"
+    "http-proxy-middleware": "2.0.9",
+    "webpack-dev-server": "5.2.1"
   },
   "browserslist": {
     "production": [