> ## Documentation Index
> Fetch the complete documentation index at: https://cantonfoundation-generated-references-json-api-reference-up.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Splice.Util

> Documentation for Splice.Util

Utility functions shared across all splice apps.

## Typeclasses

<div id="class-splice-util-hascheckedfetch-36555">
  **class** ([Show](/appdev/reference/daml-standard-library/prelude#class-ghc-show-show-65360) t, [Eq](/appdev/reference/daml-standard-library/prelude#class-ghc-classes-eq-22713) cgid, [Show](/appdev/reference/daml-standard-library/prelude#class-ghc-show-show-65360) cgid) => HasCheckedFetch t cgid **where**
</div>

> Contracts typically come in groups. For example, all contracts managed by a specific DSO party.
>
> We aim to always fetch with a specific contract group identifier to ensure that we do not mixup contracts from different groups.
>
> Note that we are not requiring `HasFetch` here, so that we can use this typeclass also for contract groups that are not templates, e.g., interface views.
>
> <div id="function-splice-util-contractgroupid-63283">
>   contractGroupId
>   : t -> cgid
> </div>

<div id="class-splice-util-patchable-41062">
  **class** Patchable a **where**
</div>

> A type class for patching values. Used in particular for changing only a subset of fields in a config value.
>
> <div id="function-splice-util-patch-72775">
>   patch
>   : a -> a -> a -> a
>
>   For records, `patch new base current` should set all fields in `current` to their value in `new` iff their value was changed in `new` compared to `base`. For other kinds of values that have field-like values (e.g. Maps with keys) the implementation should match the one for records by analogy.
> </div>
>
> **instance** Patchable [Decimal](/appdev/reference/daml-standard-library/prelude#type-ghc-types-decimal-18135)
>
> **instance** Patchable [Int](/appdev/reference/daml-standard-library/prelude#type-ghc-types-int-37261)
>
> **instance** Patchable [Text](/appdev/reference/daml-standard-library/prelude#type-ghc-types-text-51952)
>
> **instance** ([Ord](/appdev/reference/daml-standard-library/prelude#class-ghc-classes-ord-6395) k, Patchable v) => Patchable ([Map](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-map-90052) k v)
>
> **instance** Patchable [Party](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-party-57932)
>
> **instance** Patchable [Time](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-time-63886)
>
> **instance** Patchable a => Patchable ([Optional](/appdev/reference/daml-standard-library/prelude#type-da-internal-prelude-optional-37153) a)
>
> **instance** (Patchable a, [Ord](/appdev/reference/daml-standard-library/prelude#class-ghc-classes-ord-6395) a) => Patchable (Set a)
>
> **instance** Patchable [RelTime](/appdev/reference/daml-standard-library/da-time#type-da-time-types-reltime-23082)

## Functions

<div id="function-splice-util-requirematchingcontract-54053">
  requireMatchingContract
  : ([Eq](/appdev/reference/daml-standard-library/prelude#class-ghc-classes-eq-22713) t, [Show](/appdev/reference/daml-standard-library/prelude#class-ghc-show-show-65360) t, [HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) t) => [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) ()

  Require that a contract-id refers to a specific contract.
</div>

<div id="function-splice-util-require-11486">
  require
  : [CanAssert](/appdev/reference/daml-standard-library/prelude#class-da-internal-assert-canassert-67323) m => [Text](/appdev/reference/daml-standard-library/prelude#type-ghc-types-text-51952) -> [Bool](/appdev/reference/daml-standard-library/prelude#type-ghc-types-bool-66265) -> m ()

  Check whether a required condition is true. If it's not, abort the transaction with a message saying that the requirement was not met.
</div>

<div id="function-splice-util-fetchchecked-58913">
  fetchChecked
  : ([HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) t, HasCheckedFetch t cgid) => cgid -> [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) t

  Fetch a contract that is part of a specific contract group.

  The group is typically chosen by the caller to match its own group, or a more specific group.
</div>

<div id="function-splice-util-fetchcheckedinterface-8937">
  fetchCheckedInterface
  : ([HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) i, [HasInterfaceView](/appdev/reference/daml-standard-library/prelude#class-da-internal-interface-hasinterfaceview-4492) i v, HasCheckedFetch v cgid) => cgid -> [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) i -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) i

  Fetch a contract that is part of a specific contract group defined by its interface view.

  The group is typically chosen by the caller to match its own group, or a more specific group.
</div>

<div id="function-splice-util-fetchandarchive-96960">
  fetchAndArchive
  : ([HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) t, HasCheckedFetch t cgid, [HasArchive](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasarchive-7071) t) => cgid -> [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) t

  Fetch and archive a contract in one go.

  Use this when implementing choices that mutate another contract by fetching, archiving, and then creating the updated contract.
</div>

<div id="function-splice-util-fetchreferencedata-72475">
  fetchReferenceData
  : ([HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) t, HasCheckedFetch t cgid) => cgid -> [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) t

  Fetch a contract that serves as reference data.

  Use this whenever you need to fetch a contract that you do not intend to mutate.
</div>

<div id="function-splice-util-fetchbutarchivelater-86159">
  fetchButArchiveLater
  : ([HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) t, HasCheckedFetch t cgid) => cgid -> [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) t

  Fetch a contract that is not reference data, and should be archived later in some cases.

  Prefer `fetchAndArchive` over this function, as it avoids forgetting to archive the contract.
</div>

<div id="function-splice-util-fetchpublicreferencedata-76996">
  fetchPublicReferenceData
  : (HasCheckedFetch t cgid, [HasExercise](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasexercise-70422) t ch t) => cgid -> [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> ch -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) t

  Fetch a contract that offers a choice anybody to be read as reference data.
</div>

<div id="function-splice-util-fetchuncheckedandarchive-65397">
  fetchUncheckedAndArchive
  : ([HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) b, [HasArchive](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasarchive-7071) b) => [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) b -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) b

  Fetch and archive a contract in one go.

  Use this when implementing choices that mutate another contract by fetching, archiving, and then creating the updated contract.
</div>

<div id="function-splice-util-fetchuncheckedreferencedata-5520">
  fetchUncheckedReferenceData
  : [HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) t => [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) t

  Fetch a contract that serves as reference data.

  Use this whenever you need to fetch a contract that you do not intend to mutate.
</div>

<div id="function-splice-util-fetchuncheckedbutarchivelater-82900">
  fetchUncheckedButArchiveLater
  : [HasFetch](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasfetch-52387) t => [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) t

  Fetch a contract that is not reference data, and should be archived later in some cases.

  Prefer `fetchAndArchive` over this function, as it avoids forgetting to archive the contract.
</div>

<div id="function-splice-util-potentiallyunsafearchive-47027">
  potentiallyUnsafeArchive
  : [HasArchive](/appdev/reference/daml-standard-library/prelude#class-da-internal-template-functions-hasarchive-7071) t => [ContractId](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-contractid-95282) t -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) ()

  A more appropriately named version of `archive`.

  Please justify all its uses, and where possible prefer `fetchAndArchive` so that the contract group identifier is surely performed.
</div>

<div id="function-splice-util-patchscalar-11117">
  patchScalar
  : [Eq](/appdev/reference/daml-standard-library/prelude#class-ghc-classes-eq-22713) a => a -> a -> a -> a
</div>

<div id="function-splice-util-patchlistasscalar-47719">
  patchListAsScalar
  : [Eq](/appdev/reference/daml-standard-library/prelude#class-ghc-classes-eq-22713) a => \[a] -> \[a] -> \[a] -> \[a]
</div>

<div id="function-splice-util-patchlistasset-9274">
  patchListAsSet
  : (Patchable a, [Ord](/appdev/reference/daml-standard-library/prelude#class-ghc-classes-ord-6395) a) => \[a] -> \[a] -> \[a] -> \[a]
</div>

<div id="function-splice-util-deprecatedchoice-19928">
  deprecatedChoice
  : [Text](/appdev/reference/daml-standard-library/prelude#type-ghc-types-text-51952) -> [Text](/appdev/reference/daml-standard-library/prelude#type-ghc-types-text-51952) -> [Text](/appdev/reference/daml-standard-library/prelude#type-ghc-types-text-51952) -> [Update](/appdev/reference/daml-standard-library/prelude#type-da-internal-lf-update-68072) a
</div>