> For the complete documentation index, see [llms.txt](https://fifo-docs.gitbook.io/colibri/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fifo-docs.gitbook.io/colibri/colibri-core/helpers.md).

# Shared helpers

Core exports reusable helpers as well as high-level clients. Import them from [`@colibri/core`](/colibri/colibri-core/overview.md); source-directory paths and the repository's `@/` alias are not consumer import paths.

## Decimal amounts

Use strings for human-readable amounts and `bigint` for base units to avoid JavaScript floating-point rounding. These helpers do not query an asset's decimal precision; supply it from the relevant protocol or contract.

```ts
import { fromDecimals, toDecimals } from "@colibri/core";

const stroops = fromDecimals("1.2345678", 7);
console.log(stroops); // 12345678n
console.log(toDecimals(stroops, 7)); // "1.2345678"
```

Excess fractional digits are rejected by default. `excessFraction: "truncate"` explicitly truncates toward zero. `toDecimals` can trim trailing zeros or cap fraction digits without rounding. A `bigint` input to `fromDecimals` is already in base units and passes through; it is not multiplied by the scale.

## XDR and byte helpers

Stellar SDK 17 uses canonical class-based XDR and `Uint8Array`. Use SDK `toXdr()`/`fromXdr()` for serialization and Colibri's binary helpers for supported conversions; do not add a `Buffer` dependency to application code just to call Colibri.

Colibri's exported `xdr` is a helper namespace, **not** the SDK XDR constructor namespace. Alias them when both are needed:

```ts
import {
  operationHasDelegatedAuthorization,
  xdr as authXdr,
} from "@colibri/core";
import { xdr as stellarXdr } from "npm:@stellar/stellar-sdk";

const value = stellarXdr.ScVal.scvBool(true);
console.log(value.toXdr());
console.log(typeof authXdr.getAddressSignerFromAuthEntry);
console.log(typeof operationHasDelegatedAuthorization);
```

Auth-entry helpers extract the represented address, credentials, and signatures; `operationHasDelegatedAuthorization(operation)` identifies delegated credential entries on an invoke-host-function operation. These are structural tools, not cryptographic authorization verification.

## Lossless map entries

Use [`parseScValEntries`](https://jsr.io/@colibri/core/doc/~/parseScValEntries) when a map's original key types matter. The existing [`parseScVal`](https://jsr.io/@colibri/core/doc/~/parseScVal) converts keys to JavaScript values, so a String key and a Symbol key with the same text can collapse into one object property. The opt-in helper keeps both entries.

```ts
import { parseScVal, parseScValEntries } from "@colibri/core";
import { xdr } from "npm:@stellar/stellar-sdk";

const raw = xdr.ScVal.scvMap([
  new xdr.ScMapEntry({
    key: xdr.ScVal.scvString("x"),
    val: xdr.ScVal.scvU32(1),
  }),
  new xdr.ScMapEntry({
    key: xdr.ScVal.scvSymbol("x"),
    val: xdr.ScVal.scvU32(2),
  }),
]);

console.log(parseScVal(raw)); // { x: 2 } — existing behavior
const entries = parseScValEntries(raw);
console.log(entries.map(({ key }) => key.type)); // ["scvString", "scvSymbol"]
console.log(entries.map(({ value }) => parseScVal(value))); // [1, 2]
```

[`parseScValEntries`](https://jsr.io/@colibri/core/doc/~/parseScValEntries) returns a fresh array of [`ScValEntry`](https://jsr.io/@colibri/core/doc/~/ScValEntry) objects whose `key` and `value` refer to the original native ScVals. It preserves entry order and duplicates without sorting or validating canonical map order. Nested maps and vectors remain raw values. An empty or null map produces `[]`; retain the original input if that container distinction matters.

Only map inputs are accepted. Other ScVal variants throw the existing [`HLP_XDR_09`](/colibri/reference/errors/core-common-helpers-xdr.md) typed error, with `meta.data.value.valueType` identifying the received discriminant and `meta.data.value.xdrTypeName` set to `"scvMap"`.

For [events](/colibri/colibri-core/overview-1.md), pass the existing raw `event.scvalValue` to [`parseScValEntries`](https://jsr.io/@colibri/core/doc/~/parseScValEntries) when its discriminant is `scvMap`. The existing parsed event value and [`parseScVal`](https://jsr.io/@colibri/core/doc/~/parseScVal) behavior are unchanged.

## Other reusable surfaces

* Assertions and type guards narrow inputs and fail with the supplied error.
* String/boolean parsing and bounded-array helpers validate common input forms.
* Transaction helpers classify/convert envelopes and inspect RPC results.
* [`parseFailedSimulationResponse`](/colibri/colibri-core/processes/simulate-transaction.md#contract-error-diagnostics) and [`getContractErrorFromFailedSimulationResponse`](/colibri/colibri-core/processes/simulate-transaction.md#contract-error-diagnostics) expose diagnostic information without running a new simulation.
* Memoization/deferred helpers support reusable clients and asynchronous flows.

Use the [Core API index](https://jsr.io/@colibri/core/doc) for exact individual helper signatures and [all helper error contexts](/colibri/reference/errors.md). Do not assume a parse/type guard proves on-chain existence or authorization.

## Inspection helper index

These helpers complement the high-level guides. The linked references define their accepted native SDK inputs and return types.

| Task                          | Helpers and related guide                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inspect built envelopes       | [`getOperationsFromTransaction`](https://jsr.io/@colibri/core/doc/~/getOperationsFromTransaction), [`getOperationType`](https://jsr.io/@colibri/core/doc/~/getOperationType), [`getOperationTypesFromTransaction`](https://jsr.io/@colibri/core/doc/~/getOperationTypesFromTransaction); distinguish these native SDK envelopes from [ledger inspection wrappers](/colibri/colibri-core/ledger-parser.md). |
| Inspect remaining validity    | [`getTransactionTimeout`](https://jsr.io/@colibri/core/doc/~/getTransactionTimeout) returns remaining seconds or milliseconds, or `undefined` without a maximum time; see [transaction validity](/colibri/colibri-core/transaction-config.md#timeout).                                                                                                                                                     |
| Classify envelopes            | [`isTransaction`](https://jsr.io/@colibri/core/doc/~/isTransaction), [`isFeeBumpTransaction`](https://jsr.io/@colibri/core/doc/~/isFeeBumpTransaction), [`isSmartContractTransaction`](https://jsr.io/@colibri/core/doc/~/isSmartContractTransaction); see [fee bumps](/colibri/plugins/fee-bump.md).                                                                                                      |
| Inspect authorization entries | [`getAddressCredentialsFromAuthEntry`](https://jsr.io/@colibri/core/doc/~/getAddressCredentialsFromAuthEntry), [`getAddressTypeFromAuthEntry`](https://jsr.io/@colibri/core/doc/~/getAddressTypeFromAuthEntry), [`getAuthEntrySignatures`](https://jsr.io/@colibri/core/doc/~/getAuthEntrySignatures); see [authorization layers](/colibri/colibri-core/authorization.md).                                 |
| Decode untyped XDR values     | [`parseScVal`](https://jsr.io/@colibri/core/doc/~/parseScVal), [`parseScVals`](https://jsr.io/@colibri/core/doc/~/parseScVals), [`getScValTypeName`](https://jsr.io/@colibri/core/doc/~/getScValTypeName); use [spec codecs](/colibri/colibri-core/contract/values.md#runtime-specification-codecs-and-results) for ABI-aware validation.                                                                  |
| Name spec-derived events      | [`contractEventBindings`](https://jsr.io/@colibri/core/doc/~/contractEventBindings) maps ABI names to safe registry properties; see [contract events](/colibri/colibri-core/contract/events.md).                                                                                                                                                                                                           |

For decoded contract state, use [LedgerEntries](/colibri/colibri-core/ledger-entries/contracts.md) or [`Contract.getLedgerEntry`](/colibri/colibri-core/contract/invocation.md#getledgerentry). Methods marked `@internal` in the source are not alternative consumer entrypoints.