Dart is the language and Flutter is the framework#

A Flutter application uses Dart to express its logic. Flutter provides the framework used to build the interface, while the engine provides low-level services and integrates the Dart runtime. These responsibilities help us locate the application code and understand the environment it runs in. The Flutter architectural overview shows how the layers fit together. You can follow this article without first learning how widgets work.

We will use this function as an example:

1
String category(int points) {
2
  if (points >= 100) {
3
    return 'premium';
4
  }
5
  return 'normal';
6
}

String indicates that it returns text, int that it receives an integer, and return provides the result. The function returns premium for 100 points or more and normal below that value.

We will return to this function throughout the article. The diagrams and intermediate forms built around it are simplified illustrations. A real compiler may arrange its instructions differently, depending on the Dart version and the context in which the function is used.

Compilation changes the representation#

The processor executes instructions that work with registers, memory, comparisons, and branches. A compiler transforms the program to express it in those operations.

It can use several representations along the way. An abstract syntax tree, or AST, represents the program’s structure: for example, that a comparison is part of a condition. An intermediate representation, or IR, is a working format that makes it easier to analyze or transform the program before producing another format.

Dart has a program representation called Kernel. Here, the name refers to a compiler structure rather than the operating system kernel. The compiler also uses representations closer to machine code. The VM internals documentation follows the path from the frontend, which reads and analyzes the source code, through these representations.

You do not need to memorize every stage. The useful idea is that transformations between the text and the instructions change the program’s form.

JIT and AOT describe when compilation happens#

AOT still needs a runtime. The runtime supplies the services an application needs while it executes. It manages objects and memory, performs type system checks, and manages Dart’s execution contexts, called isolates. This is why you can encounter the name “Dart VM” even when an application contains code compiled ahead of time. The name does not mean that every instruction is being interpreted as bytecode.

The Dart platform overview explains this separation. It also describes web targets, which can use JavaScript or WebAssembly. This article’s ARM64 walkthrough is limited to the native target supported by flutterdec.

The binary preserves the results of compiler decisions#

Two programs written differently can end up expressing the same instructions. Renaming points to balance, rearranging an expression, or writing different comments does not require those differences to be preserved in the executable.

An optimizer can also transform the program:

These are general compilation techniques, and the LLVM optimization tutorial offers a small example you can work through. The link explains the ideas rather than describing flutterdec’s implementation or Dart’s AOT compiler.

Return to category. If the compiler can work out points before the application runs, it may replace the decision with a known result. If the result depends on a value that only becomes available at runtime, the generated program must still make that decision. When you experiment with a small function, how you call it matters just as much as its body.

That is why understanding a program’s behavior does not tell us exactly how its source was written. A decompiler can reconstruct a useful version of the logic, but it cannot recover from the binary a distinction the compiler did not preserve. This remains true even as decompilers improve.

APK is the container and ELF is the library format#

An APK is a ZIP-based package. It can contain resources, Android code, and native libraries. Android places these libraries under paths such as lib/<abi>/lib<name>.so. The folder name arm64-v8a identifies the ARM64 variant. The NDK documentation explains this packaging.

For the case we are interested in:

A .so library uses the ELF format, which describes file regions, addresses, and other metadata needed to work with native code. A snapshot is a saved representation of structures that the runtime needs to reconstruct. In section 5, we will look at what it means to save their objects and relationships.

The flutterdec loader opens the APK or ELF, checks that the target is AArch64, and recovers regions identified by symbols such as _kDartIsolateSnapshotData and _kDartIsolateSnapshotInstructions. It also handles the equivalent VM regions.

Data and Instructions separate two kinds of information: snapshot data and executable instructions. The VM/isolate distinction tells us which runtime scope a region belongs to. For now, remember that the file contains several regions, each with a different role.

To read the file, the loader needs the expected snapshot regions and valid bounds for each one. The .so extension alone does not tell it where Dart’s data and instructions are.

Serializing an object is only the beginning#

Serialization means representing data as a sequence that can be stored or transmitted. Deserialization means interpreting that sequence to reconstruct a usable representation.

With a list of numbers, the problem seems straightforward. Objects that point to one another introduce another challenge: preserving their relationships and identity.

Imagine that two functions belong to the same class. Reconstructing a separate copy of the class for each function would lose the fact that both point to the same object. There can also be references to objects that appear later, or paths that lead back to the original object.

This structure is called an object graph: objects are nodes, and references are links. The Dart snapshot documentation describes how the runtime serializes that graph. An AOT snapshot packages the objects and relationships needed to start and run the program. It is a starting state for execution, not a recording of what a user does after opening the application.

An identifier is not a memory address#

An identifier can be used to store a reference. Saying “this field points to object 300” makes it possible to resolve the relationship once the objects are known.

It helps to distinguish these numbers before looking at the Serwalker code:

They are not interchangeable. A CID does not locate a function, an object identifier is not an ARM64 address, and an offset needs a base before it can become an address.

The difference between an offset within a file and a virtual address also matters: a library does not have to be loaded at an address that numerically matches the position of its bytes on disk.

The runtime has objects the programmer did not write#

When we read Function or Code in Serwalker, we are talking about internal structures that describe functions and code. This does not mean the application declared classes with those names.

The runtime maintains structures to represent libraries, classes, functions, types, strings, and other elements. Part of their value for reverse engineering is that they can connect a name, an owner, and a range of instructions.

Reading a header requires knowing the format#

Before walking through objects, parse_header checks an identifying marker, reads the snapshot size and kind, and obtains its format version and features.

The snapshot hash identifies the format that Serwalker must understand. It is a compatibility identifier, not a hash of the APK’s contents.

The parser checks for:

• A FullAOT snapshot.

• The snapshot hash 78da37fed6bf1489361a312568249f3f used by Dart 3.11.1.

• The compressed-pointers feature.

compressed-pointers indicates that certain object references use a shortened representation. This is a property of the object representation, separate from APK compression.

Serwalker also uses details of the ARM64 layout. Dart can change the snapshot format without changing the target processor, so recognizing the instructions does not automatically tell us how to read the objects.

The Stream type keeps a cursor pointing to the next bytes to read. Some fields have a fixed width. Several integers in the snapshot body use Dart’s variant of LEB128, which encodes a number using a variable number of bytes. Reference identifiers use a separate reader, read_ref_id, because they follow a different encoding. Reading a field with the wrong method can move the cursor to the wrong position and misinterpret everything that follows.

A binary parser therefore has to get two things right at every step: what the field means and how many bytes belong to it.

Clusters group objects that share a reading scheme#

A cluster groups objects that share a set of deserialization rules. The format handles them together so that the reader can apply those rules to the whole group.

The header reports how many clusters there are. For each one, Serwalker reads its tags, determines its CID, and selects an implementation through decide_cluster. There are implementations for classes, functions, code, strings, arrays, the object pool, and other structures.

The tags also include properties such as whether an object is canonical or immutable. Here, “canonical” relates to the shared representation that the runtime maintains for certain equivalent values. These details affect how the group is identified and must be preserved while walking through it.

The benefit of this organization is that each implementation knows how to read the fields of its object type. An array of variable length and a function structure do not have to be interpreted as if they had the same format.

A first pass creates objects and a second fills them#

This is one of the most important mechanisms in the deserializer.

Consider this illustrative graph, with invented identifiers. The numbers are reference_id values: they identify specific objects in the snapshot, not CIDs.

1
flowchart TD
2
    C["Class with ID 100"] -->|"functions"| A["Array with ID 200"]
3
    A --> F["Function with ID 300"]
4
    F -->|"owner"| C

When reading class 100, array 200 might not have been reconstructed yet. And on reaching function 300, there is a reference back to the class.

Serwalker separates the work into two passes over all clusters:

It does not finish an entire cluster before starting the next one: first it performs the allocation phase across the whole set, then the fill phase in the recorded order.

Numbering in parse_clusters starts after the base objects declared by the snapshot. At the end of allocation, Serwalker checks that the total reference count matches the header. This gives it an early check that the stream and its object counts agree.

Fields retain identifiers that can later be looked up using utilities such as find_object_by_id. This makes it possible to represent shared relationships, forward references, and cycles without expanding each reference into a new copy.

The idea is similar to loading database rows with identifiers and then resolving their relationships. That analogy helps explain the dependencies between objects. The actual snapshot format is binary and specific to Dart.

Check your understanding. If function 300 points to class 100, should you create a new class? No: you should resolve the reference to the representation associated with that identifier.

Roots help locate important structures#

After the clusters, Serwalker processes the program roots: references that provide access to relevant structures.

parse_roots reads the ObjectStore, field tables, and a dispatch table. The dispatch table helps organize the targets of calls. The ObjectStore gives us access to another structure we need next: the global object pool.

The roots have a concrete use: the model producer looks up global_object_pool in the ObjectStore and resolves the corresponding identifier. This is how it identifies the global pool through a relationship in the snapshot.

Following this reference tells us which pool the program uses globally. That relationship lets the next stages connect a pool access in the code to the right collection of objects and values.

Connecting functions to instructions#

Knowing a function name still does not tell us which bytes it executes. To connect those worlds, Serwalker uses the instruction table and relationships between Function and Code objects.

The table contains offsets to instruction payloads. Here, a payload is the associated block of code bytes. A function’s code_index field uses a numbering scheme that the implementation converts into a table index: for a nonzero value, it subtracts one. If code_index is 3, it looks up entry 2.

The table also records first_entry_with_code, the point at which its entries start corresponding to objects in CodeCluster. If that value is 2, table entry 2 corresponds to the first object in the cluster. Serwalker uses this rule to move from a table index to the corresponding object reference.

The runtime can discard a Code metadata object while keeping its machine instructions. The function producer handles both cases: entries with retained Code objects and entries whose instructions must be located through the table.

Once the offset is known, adding it to the virtual base address of the image gives us the payload address. For example:

1
Virtual base address of instructions: 0x700000
2
Payload offset:                      0x1200
3
Virtual address of the payload:      0x701200

The producer turns these offsets into address ranges, giving later analysis a starting address and a number of bytes to read. For a retained Code object, the range covers the whole payload, which may contain multiple entry points.

Deferred code belongs to units that load separately. Its metadata can appear in the main snapshot even when its instructions are elsewhere. Serwalker leaves those entry points unresolved and omits their functions from the model.

Producing a usable model#

The reconstructed objects now need a form that the rest of flutterdec can use. ProgramModel v4 provides that common schema. The model producers turn libraries, classes, functions, and pool entries into records, following references to recover names and ownership information. Function records also connect that information to the address ranges found in the instruction image.

The [pool producer][sw-pool] walks the selected ObjectPool in order, keeping its exported indices aligned with the slots used by the machine code. It exports string contents and immediate values. For other objects, it may only have a type and a reference ID. Recognizing those does not by itself reveal the complete value or resolve a call target. The optional fields in ProgramModel v4 let later stages work with the facts available without inventing the missing ones.

Object references also have to account for base objects, which occupy the first IDs in the snapshot. Serwalker starts numbering its newly read objects after them. A reference into that initial range remains unresolved if the corresponding [base object][sw-base] has not been reconstructed.

The schema also records what information is available and where it came from. Later stages can use a function’s address range to select instructions, its recovered name to label calls, and pool values to explain loads. They can do this without repeating the snapshot deserialization or assuming that every optional field has been filled.

Registers are working locations inside the processor#

For this section, it is enough to distinguish registers from memory. Registers are small areas of working storage inside the processor. Memory contains instructions, objects, and other data that can be loaded into them.

In AArch64, you will encounter register names such as x0 and x27. An ldr instruction loads a value from memory, cmp compares values, and branches change which instruction executes next. The Arm A64 guide explains these operations.

An ABI defines conventions that let different pieces of code work together: how they pass arguments, which registers they reserve, and how they organize certain accesses. In addition to the architecture, flutterdec needs to recognize Dart runtime conventions.

The flutterdec disassembler uses Capstone to decode instructions and adds annotations for Dart’s conventions. For ARM64 code, those annotations include pool accesses through x27, also called PP.

The object pool holds values that the code uses#

The ObjectPool lets code access objects and constants through entries. Strings are an easy example to visualize, but the pool can also contain other kinds of values.

Let’s return to category. One of its paths might load the object representing premium from the pool. The instruction gives us a location relative to the pool base. Deserializing the pool lets us connect that location to a value.

Consider this illustrative instruction:

1
ldr x0, [x27, #0x28]

This reads as “load into x0 the value located 40 bytes from the base held in x27.” 0x28 equals 40.

The pool geometry declared by Serwalker places the first entry 16 bytes from the base and uses entries of 8 bytes. With those values:

1
Index = (displacement − start of entries) / entry size
2
Index = (40 − 16) / 8
3
Index = 3

Suppose slot 3 contains a reference to premium. We can now read the instruction as a load of that string object. This interpretation depends on both the instruction and the pool’s contents and layout. The layout describes where the entries begin and how much space each one occupies. The flutterdec model stores that geometry and checks whether a displacement can be converted into an entry index.

Those offsets and entry sizes belong to the ARM64 pool layout. Even with compressed-pointers, its slots occupy eight bytes. Compressing certain object references does not make every field or structure in the binary four bytes wide.

Finding strings does not prove how they are used#

Suppose that, while scanning the bytes, we find normal and premium, in that order. We only know the scan order. Nothing proves that they are pool entries 0 and 1, or that this function uses them.

ProgramModel v4 distinguishes hardware indices, tied to the actual layout, from ordinal indices that simply enumerate a producer’s output. If the available metadata does not justify converting a displacement into a pool index, the disassembler can keep it as poolOff[...]. The expression preserves what the instruction tells us without attaching a string to the wrong location.

Deserialization supplies the missing connection: which object or value belongs to the location that the machine code accesses.

A Dart reference also has a representation#

The runtime distinguishes immediate small integers from object references using tag bits. As a result, without additional information, a number observed in a register cannot always be interpreted directly as an ordinary integer or an address.

Understanding these representations helps us interpret what an instruction is actually moving or comparing. The Object representation section of the GC documentation explains tagged values without requiring a tour of the entire garbage collector.

A dedicated IR organizes what was recovered#

Once the instructions have been disassembled, flutterdec builds its own working representation. This LLIR, or low-level IR, preserves addresses, operations, text, and targets.

The IROp type distinguishes these categories:

flutterdec builds this IR from the instructions in the binary. It becomes the analyzer’s working model during decompilation. The compiler’s original IR is a separate representation that this process does not recover.

For teaching purposes, we can represent our example like this:

1
compare points with 100
2
if less, go to NORMAL
3

4
PREMIUM:
5
    result = pool[3]
6
    go to EXIT
7

8
NORMAL:
9
    result = pool[4]
10

11
EXIT:
12
    return result

For this illustration, slot 3 holds premium and slot 4 holds normal. We use a short notation to make the flow easy to follow. The --emit-ir option writes this kind of information as JSON. A compiler may arrange the branches differently while preserving the same decision.

Basic blocks describe stretches of execution#

A basic block is a sequence of instructions traversed without internal branches in ordinary control flow. Decisions connect blocks to one another.

The control-flow graph, or CFG, represents these blocks and the possible paths between them. Serwalker’s object graph connects objects through references. The CFG connects blocks through possible execution paths.

1
flowchart TD
2
    E["Compare points with 100"] -->|"Less than"| N["Load normal"]
3
    E -->|"Greater than or equal to"| P["Load premium"]
4
    N --> S["Return result"]
5
    P --> S

In the CFG builder, flutterdec marks block beginnings at the entry point, at jump targets, and after instructions that end a stretch of execution. It then records successors and predecessors: where each block can go and where it can be reached from.

The graph makes it easier to study a property that is less clear in a list of instructions: the example’s two branches return to a common point.

Recovering a condition requires tracking values#

Recognizing that a conditional branch exists does not, by itself, reveal the high-level expression. The comparison must be interpreted, and the values that reach it must be tracked.

The expression analysis works with instructions and register state to build readable approximations. A sequence of moves, loads, and operations may end up expressed as a comparison or a field access. If a relationship is missing, register names, memory locations, or partial expressions may remain.

The kind of call also matters. A direct call contains a target that can be resolved to a known address. An indirect call obtains its target from a computed or loaded value. Resolving the latter may require information that the static analysis does not yet have.

A method name found near a call may provide context, but it does not replace evidence that the call targets that method.

Sharing code where branches rejoin#

In the previous diagram, the “Return result” block lies on both paths. If the emitter expanded each path separately, it could duplicate the code they share. In large graphs, those duplications can grow quickly.

To organize control flow, Regions::build computes dominance and postdominance relationships:

• A block dominates another if every path from the entry point to that other block passes through it.

• A block postdominates another if every path from that other block to an exit passes through it.

In our small graph, the comparison comes before both branches, and the shared return comes after them. These relationships help identify the condition and the point where control flow rejoins.

Cycles require recognizing paths that return to a header. When that header dominates the block from which the path returns, a natural loop can be identified. This relationship helps the emitter express it as a repetition structure.

These are graph concepts applied to a program. Their purpose here is concrete: they help determine where to open and close an if, where to place a loop, and which block should be emitted only once.

Some arrangements of jumps do not fit this pattern of conditions and loops. The emitter can use another strategy for those cases, although parts of the resulting control flow may remain unresolved.

The compiler also introduces support instructions#

Suppose we find a branch before the body of a function. It could be a condition in the program, but it could also be a check introduced to protect execution.

flutterdec recognizes a stack-limit check pattern and classifies it as RuntimeCheck. The stack is a region used to organize part of the state of function calls. If that check were interpreted as business logic, it would add a condition and perhaps a loop that the developer never wrote.

Reconstructing structures therefore also requires distinguishing the application’s work from the runtime’s support work.

From expressions to pseudocode#

After structuring the flow, the emitter cleans up expressions, compacts repeated patterns, and adds names or types. Some of that context comes from recovered data. Other details are inferred to make the operations easier to read.

For our example, a simplified pseudocode rendering might look like this:

1
String recoveredFunction(int value) {
2
  if (value >= 100) {
3
    return 'premium';
4
  }
5
  return 'normal';
6
}

The comparison and its two outcomes are the behavior we want to recognize. Function names, parameter names, and the arrangement of the branches may differ from the source text.

The signature is also a reconstruction. Its arguments and types reflect what the emitter could model, so they may be less precise than the original declaration.

Check your understanding. Does seeing a while in the pseudocode prove that there was a while in the source? No: it shows that the emitter represented part of the control flow as a loop. The original structure could have been written differently.

A common model connects the analysis stages#

The rest of the pipeline needs objects, names, and code ranges in a common shape. ProgramModel v4 provides that contract. It describes libraries, classes, functions, and the object pool, along with the capabilities of the recovery process and the provenance of each fact. This lets the later stages work with the information they need without having to parse the snapshot themselves.

Different recovery approaches supply different amounts of context:

The Python producer can try different backends to obtain this information. When a compatible metadata recovery path is unavailable, the core can still identify code candidates from the instructions. That gives the disassembler a starting point, even when names and object relationships are missing.

Read the files as different views of the same program#

Provenance tells you how a fact entered the model:

Capabilities describe how much of a domain was recovered: complete, partial, or unavailable. A missing function name stays missing, which lets you distinguish an unknown name from a recovered one.

For example, an exact name in an obfuscated binary is the obfuscated name stored in the snapshot. The label describes how the name was recovered. It does not restore the spelling that existed before obfuscation.

The Flutter documentation on obfuscation explains that this mechanism changes symbols and does not encrypt resources. Useful information may therefore still be available for analysis, even if the names are less expressive.

Use quality metrics to decide where to look#

The quality counters help you find parts of the output that need closer inspection. They track placeholder conditions, unresolved control flow, the proportion of indirect calls, and disassembly coverage, among other properties.

Use these counters to locate gaps and compare runs. They do not measure the percentage of original source code recovered. A readable condition may still depend on incomplete information, so the operations behind that condition matter as much as its presentation.

The CLI sets --max-placeholder-ifs to zero by default. A placeholder condition can therefore fail the quality gate after the artifacts have been written. If that happens, open quality.json to see which threshold was exceeded and continue inspecting the generated files. An earlier loading or analysis error may prevent artifacts from being written.

To understand a branch, follow it through the pseudocode, the IR, and the instructions. If an expression contains a string or a name, check how the producer linked that value to the code. You can then connect the behavior you are studying to the bytes and objects that support it.

Inspect the app and run the analysis#

Follow the [installation guide][source-1] to set up flutterdec. With flutterdec installed and an Android AOT APK containing the ARM64 variant, begin by inspecting the app:

1
flutterdec info ./app.apk --json

Find the snapshot_hash and features in the output. Compare them with the snapshot format Serwalker supports, as described in Section 6. A matching architecture tells you how to decode the instructions. The snapshot hash and features tell you whether the parser understands the serialized objects. Once the format matches, run:

1
flutterdec decompile ./app.apk -o ./out \
2
  --adapter-backend internal --emit-asm --emit-ir

The --adapter-backend internal option selects Serwalker. The --emit-asm and --emit-ir options add disassembly and IR files alongside the pseudocode. Check report.json to see what information was recovered, then open a small function in all three forms.

Tracing an entire condition#

Open the artifacts and work through these steps:

1. Find a small function and a condition you can recognize in the pseudocode.

2. Locate its blocks in the IR and the targets of both branches.

3. Find the corresponding comparison and branch in the disassembly.

4. If there is a pool load, note the displacement and check whether a geometry is available that lets you obtain an index.

5. Check where the data associated with that entry came from.

6. Write down which conclusion is supported and which detail is still missing.

Record your conclusion in concrete terms, such as “this branch loads the object from entry 3 and returns the result.” Note how you identified the branch, linked the load to the pool, and resolved the object. Those steps make the conclusion reproducible.

The default app-unknown scope includes code classified as application code and code whose owner is unknown. Package dependencies may appear too. Use --app-package to focus on a package or --target to select a function, as described in the CLI reference.

Getting started with the implementation#

The code becomes less opaque if you approach it through questions:

To compare the format with its original implementation, the [Dart 3.11.1 SDK deserializer][sdk-snapshot] is an advanced reading option. Look for Deserializer::Deserialize and compare the separation between allocation and filling with Serwalker. [datastream.h][sdk-stream] lets you explore the binary readers further. This reading is much more useful after you understand the graph example.