> For the complete documentation index, see [llms.txt](https://emeditweb.gitbook.io/pulsar-stellar-sdk/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://emeditweb.gitbook.io/pulsar-stellar-sdk/sdk-reference/decoding.md).

# Decoding

The functions that turn Soroban `ScVal` values into the SDK's wire-faithful `DecodedValue`. This is the RPC path's decoder; the indexer decodes on its own side and serves the same shape, so a consumer sees one representation whichever source an event came from.

For the taxonomy itself, and the reasoning behind wide integers as strings and the `unknown` fallback, see [Decoded values](/pulsar-stellar-sdk/concepts/decoded-values.md).

## `decodeScVal(value)`

```ts
decodeScVal(value: xdr.ScVal): DecodedValue
```

Decodes one `ScVal` into a [`DecodedValue`](/pulsar-stellar-sdk/sdk-reference/schemas-and-types.md#decodedvalue-and-decodedmapentry).

**Never throws.** An unrecognized variant, or one whose payload does not decode, comes back as `{ type: 'unknown', xdr }` carrying its base64, which keeps one malformed value from discarding every other event in a response.

The mapping, from ADR-023:

* Integers wider than 32 bits (`u64`, `i64`, `u128`, `i128`, `u256`, `i256`, `timepoint`, `duration`) become strings. `u32` and `i32` stay numbers.
* `bytes` becomes lowercase hex.
* `vec` becomes an array of `DecodedValue`; `map` becomes an ordered array of `{ key, value }` pairs.
* Everything else maps to its named variant; anything unknown becomes `{ type: 'unknown', xdr }`.

```ts
import { decodeScVal } from '@pulsar-stellar/sdk';

const decoded = decodeScVal(scVal);
if (decoded.type === 'i128') {
  const amount = BigInt(decoded.value);
}
```

## `decodeTopics(topics)`

```ts
decodeTopics(topics: readonly xdr.ScVal[]): DecodedValue[]
```

Decodes an event's topics in order, applying `decodeScVal` to each. This is the faithful counterpart to [`parseTopics`](/pulsar-stellar-sdk/sdk-reference/contracts.md#parsetopicstopics), which is ergonomic but lossy. Use `decodeTopics` when the result is stored, compared, or sent anywhere.

## `eventNameFromTopics(topics)`

```ts
eventNameFromTopics(topics: readonly DecodedValue[]): string
```

Reads the event name from its leading topic. Soroban puts the event's Symbol first, which is what the indexer stores as `name`. Returns that symbol's value, or the empty string when the first topic is not a symbol, meaning the emitter did not follow the convention. It returns `''` rather than guessing a name.

```ts
import { decodeTopics, eventNameFromTopics } from '@pulsar-stellar/sdk';

const topics = decodeTopics(rawTopics);
const name = eventNameFromTopics(topics); // '' if the first topic is not a Symbol
```

## `DecodedValueSchema`

```ts
const DecodedValueSchema: z.ZodType<DecodedValue>
```

The Zod schema that validates a [`DecodedValue`](/pulsar-stellar-sdk/sdk-reference/schemas-and-types.md#decodedvalue-and-decodedmapentry). It is a discriminated union on `type`, built lazily because the type is recursive: `vec`, `map`, and `tuple` each contain more decoded values. Use it to validate a decoded value that arrived from outside your own `decodeScVal` call, for example one deserialized from storage.

## `DecodedMapEntrySchema`

```ts
const DecodedMapEntrySchema: z.ZodType<DecodedMapEntry>
```

Validates one `{ key, value }` entry of a decoded map, where both sides are themselves `DecodedValue`. A map is carried as an ordered array of these rather than an object or a `Map`, so a key's type, the wire ordering, and any duplicate keys all survive. See [Decoded values](/pulsar-stellar-sdk/concepts/decoded-values.md#map-is-an-ordered-array-not-an-object).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://emeditweb.gitbook.io/pulsar-stellar-sdk/sdk-reference/decoding.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.