Amend documentation in Builtins.Internal about budgeting and invariants on Bytestring builtins

Author: SeungheonOh

plutus-tx/src/PlutusTx/Builtins/Internal.hs

@@ -18,8 +18,15 @@
   Most users should not use this module directly, but rather use 'PlutusTx.Builtins'.
 
   Please note that the documentation for each function will only include operational invariants
-  if there are any. This documentation assumes type system correctly enforces and prevents any structural
-  errors on the generated UPLC. See Note [Structural vs operational errors within builtins].
+  if there are any. This documentation assumes that the type system correctly enforces and
+  prevents any structural errors on the generated UPLC. See Note [Structural vs operational errors
+  within builtins].
+
+  Also note that all builtin functions will fail if the CEK machine exceeds its evaluation budget.
+  Builtin functions with dynamic costing are particularly prone to budget overruns: for example,
+  addInteger and appendByteString differ cost based on input size, so supplying very large integers or
+  byte strings will cause these functions to abort when the budget limit is reached and fail.
+  See Note [Budgeting].
 -}
 module PlutusTx.Builtins.Internal where
 
@@ -893,9 +900,11 @@ bls12_381_finalVerify (BuiltinBLS12_381_MlResult a) (BuiltinBLS12_381_MlResult b
 CONVERSION
 -}
 
-{-| Converts the given integer to a bytestring. The first argument specifies
-endianness (True for big-endian), followed by the target length of the resulting bytestring
-and the integer itself. See 'PlutusCore.Bitwise.integerToByteString' for its invariances.
+{- | Converts the given integer to a bytestring. The first argument specifies
+ endianness (True for big-endian), followed by the target length of the resulting bytestring
+ and the integer itself. Fails if the target length is greater than 8192 or if the length
+ argument is 0 and the result won't fit into 8192 bytes.
+ See 'PlutusCore.Bitwise.integerToByteString' for its invariants in detail.
 -}
 integerToByteString
   :: BuiltinBool
@@ -1045,13 +1054,14 @@ writeBits (BuiltinByteString bs) (BuiltinList ixes) (BuiltinBool bit) =
     BuiltinSuccessWithLogs logs bs' -> traceAll logs $ BuiltinByteString bs'
 {-# OPAQUE writeBits #-}
 
-{-| Creates a bytestring of a given length by repeating the given byte.
-Fails if the byte, second argument, is not in range @[0,255]@ or the length is negative.
+{- | Creates a bytestring of a given length by repeating the given byte.
+Fails if the byte, second argument, is not in range @[0,255]@, the length is negative,
+or when the length is greater than 8192.
 -}
-replicateByte
-  :: BuiltinInteger
-  -> BuiltinInteger
-  -> BuiltinByteString
+replicateByte ::
+  BuiltinInteger ->
+  BuiltinInteger ->
+  BuiltinByteString
 replicateByte n w8 =
   case Bitwise.replicateByte n (fromIntegral w8) of
     BuiltinFailure logs err ->