Skip to content
← All posts
· Delta1 Labs ObfuscationNebula

Obfuscating Orleans Grains Without Breaking Cluster Routing

Orleans routes every grain call by strings in the cluster manifest — a GrainInterfaceType and a GrainType derived by default from your .NET type names. Rename a grain and the identity moves, orphaning persisted state and breaking cross-silo calls. Here is how to decouple identity with [Alias]/[GrainType] and still obfuscate aggressively.

An Orleans application is a strong obfuscation candidate and an easy one to break. The grains are the product — the stateful actors that hold your pricing, settlement, matchmaking or fraud logic and run headless on a server you may not control — and almost all of that code can be renamed, string-encrypted and virtualized freely. But Orleans has a seam a naive pass walks straight into, and the failure mode is the quiet kind: the cluster starts, a client connects, a call is dispatched, and the grain that handled it yesterday is suddenly not registered, or its persisted state has vanished. Nothing in your own code threw; Orleans simply could not find the thing you renamed.

The cause is specific to how Orleans decides what a grain is, and once you see it the fix is a handful of attributes. This post is about that mechanism — how Orleans derives a grain’s identity from its type, where those identities travel, and how to protect the valuable interior with Nebula.NET while leaving the identities exactly where the cluster expects them.

TL;DR

  • Orleans routes by strings in the cluster manifest, not by .NET type identity: a GrainInterfaceType (which interface) and a GrainType (which grain class), both derived by default from your type names.
  • A GrainId begins with the GrainType, so it keys persisted state and reminders. Change the GrainType and that state is orphaned.
  • Serialization is numeric — the modern serializer encodes fields by their [Id(n)] tag, so renaming fields is safe. Only the type identity (its [Alias] or full name) is name-based.
  • The robust fix is to decouple identity from the symbol: pin [GrainType], [GrainInterfaceType] and [Alias] to fixed strings, then rename the types freely.
  • Everything behind the grain — services, helpers, algorithms — renames, encrypts and virtualizes with nothing to keep.

Why obfuscate an Orleans app at all

The grain classes are where your intellectual property lives: the method that scores a transaction, the state machine that settles a trade, the actor that recomputes a price when the market moves. That code is deployed as a DLL to a silo host — frequently one your customer operates — and anyone with file access can open it in a decompiler and read it back as clean C#. The grain tier is also where sensitive constants cluster: downstream endpoint URLs, partner credentials, signing material, provider names. Raising the cost of reading your own shipped logic back out of that binary is exactly the legitimate case for obfuscation.

How Orleans builds a grain’s identity

Here is an ordinary grain interface, its implementation and a serializable state type, each annotated the modern Orleans way:

namespace Contoso.Trading.Abstractions;

public interface IOrderGrain : IGrainWithStringKey
{
    Task<decimal> Settle(decimal amount);
}
namespace Contoso.Trading.Grains;

public sealed class OrderGrain : Grain, IOrderGrain
{
    private readonly IPersistentState<OrderState> _state;

    public OrderGrain([PersistentState("order")] IPersistentState<OrderState> state)
        => _state = state;

    public async Task<decimal> Settle(decimal amount)
    {
        // proprietary — the reason this grain exists
        var net = _state.State.ApplySettlement(amount);
        await _state.WriteStateAsync();
        return net;
    }
}

[GenerateSerializer]
public sealed class OrderState
{
    [Id(0)] public decimal Balance { get; set; }
    [Id(1)] public int Version { get; set; }

    public decimal ApplySettlement(decimal amount) { /* ... */ return Balance; }
}

A caller resolves the grain by interface and invokes it:

var grain = client.GetGrain<IOrderGrain>("order-7b1e");
var net = await grain.Settle(149.95m);

Nothing in that call names a silo, an address or a routing key. Orleans works it all out from type identity expressed as strings. Two strings, specifically, computed from your types and published into the cluster manifest that every silo and client shares:

  • A GrainInterfaceType for IOrderGrain — by default derived from the interface name ("ordergrain" plus namespace disambiguation). It tells the cluster which contract a call targets, and it is how a client’s generated grain reference is matched to an implementation somewhere in the cluster.
  • A GrainType for OrderGrain — by default derived from the class name ("ordergrain"). It names which grain class should be activated to handle the call, and it drives placement.

The call itself becomes a message carrying the GrainInterfaceType, a method identifier, and a target GrainId. And the GrainId is the quiet one: it is GrainType + / + your key —

ordergrain/order-7b1e

— so the GrainType string is literally the prefix of the identity under which Orleans places the activation, stores [PersistentState], and registers reminders. The storage provider writes OrderState under a key built from that GrainId. Change the GrainType and every previously written row points at a grain the cluster no longer knows.

Client / grain referenceclient.GetGrain<IOrderGrain>("order-7b1e")call internals renamed · encryptedpinned identity →GrainInterfaceType: "order"GrainId: order/order-7b1eCluster manifest + placementmatch "order" → silo activationGrainType keys state + remindersSilo / grain activationOrderGrain : Grain, IOrderGraininterior renamed · encrypted · virtualized[GrainType("order")] pins identity →GrainType: "order"[PersistentState] key unchangedPin identity with attributes, then obfuscate the typeBoth sides advertise the identical string → routing + persistence holdGrain classes, state, services: renamed, string-encrypted, virtualizedRename a type without pinning → identity moves → call cannot be placed

What is not name-based: serialization

A relief hides in OrderState. Orleans’ modern serializer is numeric: the source generator emits a serializer that reads and writes field 0, field 1, and so on, keyed by the [Id(n)] tag — never by the field name. After obfuscation the field symbol Balance and the generated serializer that references it rename together, inside the same assembly, and the wire bytes are still numbered. So renaming the properties of a [GenerateSerializer] type is completely safe, as long as the [Id(n)] tags stay. The one name-based part is the type reference the serializer writes so the receiver knows what to construct — and that uses the type’s [Alias] or, absent one, its full name.

The robust fix: decouple identity from the symbol

The naive instinct is to keep-list every grain and serializable type. That works, but it leaves the most valuable classes in your assembly readable. The better move is to make Orleans’ identity independent of the .NET type name, so the symbol is free to be destroyed while the manifest keeps advertising a fixed string. Three attributes do it:

namespace Contoso.Trading.Abstractions;

[GrainInterfaceType("order")]               // pins the interface identity
public interface IOrderGrain : IGrainWithStringKey
{
    [Alias("settle")]                       // pins the method identity
    Task<decimal> Settle(decimal amount);
}
[GrainType("order")]                        // pins the grain identity + GrainId prefix
public sealed class OrderGrain : Grain, IOrderGrain { /* ... */ }

[GenerateSerializer, Alias("order-state")]  // pins the serialized type identity
public sealed class OrderState
{
    [Id(0)] public decimal Balance { get; set; }
    [Id(1)] public int Version { get; set; }
}

With these in place, the cluster advertises "order", matches calls on "order", builds GrainIds starting with "order", and writes state under "order" — all regardless of what the classes are called. Nebula.NET is now free to rename OrderGrain to a, IOrderGrain to b, Settle to c, and OrderState to d, and nothing on the wire or in storage moves.

Migration note: pin each identity to the current default value first — the string the un-obfuscated build already advertised — so existing GrainIds, reminders and persisted state resolve unchanged. Only after you have confirmed nothing moved should you obfuscate. Pinning to a new string is a data migration, not an obfuscation step.

The keep-list (when you cannot add attributes)

If you are obfuscating a grain assembly you do not own the source of, or you simply cannot touch the types, fall back to keeping the identities by name. Model the grain interfaces under one namespace and nebula.config.json reads:

{
  "schemaVersion": 1,
  "inputs": [
    "publish/Contoso.Trading.Grains.dll",
    "publish/Contoso.Trading.Abstractions.dll"
  ],
  "outputDirectory": "protected",

  "preservePublicApi": false,
  "encryptStrings": true,
  "controlFlowObfuscation": true,

  "renaming": {
    "rules": [
      { "pattern": "Contoso.Trading.Abstractions.*", "action": "keep", "scope": "type-and-members" },
      { "pattern": "*State",                         "action": "keep", "scope": "type" },
      { "pattern": "Contoso.Trading.*",              "action": "rename" }
    ]
  }
}

The first rule pins every grain interface and its methods (the method name feeds the method identity). The second keeps the serializable state types by name so their default type reference survives — a blunter substitute for [Alias]. Everything else — grain classes, services, helpers — is renamed. String encryption and control-flow obfuscation apply everywhere, including the kept types, because neither touches names. This protects less than the attribute approach, because the grain class names leak; prefer the attributes whenever you can edit the code.

The audit: what moves, what doesn’t

Walk every identity that leaves the assembly, and the plan writes itself.

  • Grain interface types and their methods — build the GrainInterfaceType and method identities a client and every silo match on. Pin with [GrainInterfaceType] + [Alias], or keep by name.
  • Grain classes — build the GrainType, which prefixes every GrainId and keys persisted state and reminders. Pin with [GrainType], or keep by name.
  • [GenerateSerializer] types — identified on the wire by alias or full name; fields identified by [Id(n)], not name. Pin the type with [Alias] and keep the [Id] tags; the fields rename freely.
  • Grain class interiors — the Settle body, private helpers, the services it calls. Resolved inside the process by DI and type identity; nothing on the wire names them. Rename, encrypt, virtualize.
  • Provider and storage names — "order" in [PersistentState("order")], stream namespaces, string literals. Data you reproduce at runtime; string encryption leaves the runtime value intact. No action needed.

One surface to pin, then — the grain and interface identities — and the entire interior is fair game.

Protecting the interior

Pinning an identity does not mean leaving anything readable. The manifest strings stay stable while everything behind the grain goes dark. String encryption hides the downstream URLs, credentials and provider names the grain tier accumulates. The strongest transforms — code virtualization and whole-method encryption, both Pro features in Nebula.NET — go on the crown jewels: the settlement, scoring or pricing methods, applied to that handful of methods rather than the whole assembly:

[GrainType("order")]
public sealed class OrderGrain : Grain, IOrderGrain
{
    [Obfuscation(Feature = "virtualization")]   // Pro — the algorithm, not the plumbing
    public async Task<decimal> Settle(decimal amount) { /* ... */ return 0m; }
}

Renaming and control-flow obfuscation run broadly underneath, turning the rest of the grain interiors into meaningless symbols and tangled branches while the identity the cluster routes by stays exactly where it was.

Folding protection into the build

Protect the published output, and only on the build server so local debugging stays fast and readable:

dotnet publish Contoso.Trading.Silo -c Release -o publish
nebula protect --config nebula.config.json
<Target Name="NebulaProtect" AfterTargets="Publish"
        Condition="'$(CI)' == 'true'">
  <Exec Command="nebula protect --config nebula.config.json" />
</Target>

Ship the protected/ folder, not the raw publish folder. nebula protect returns a non-zero exit code on failure, so a broken protection step fails the build instead of shipping a silo that renamed a grain the rest of the cluster still routes by.

Verifying it actually works

Unit tests will not catch this: a TestCluster that builds grains in one process from the same binary sees consistent identities and passes even when the identity would diverge across a real, heterogeneous deployment. Two checks will. First, run it against a multi-silo cluster built from the protected DLLs, ideally with one silo still on the previous build to mimic a rolling upgrade, and confirm a client call places and a grain activates. A call that fails to find a registered grain type, or a grain whose previously persisted state comes back empty, is the exact signature of a moved identity — compare the GrainType/GrainInterfaceType the manifest advertises against what the other silo expects.

Second, open the shipped assembly in a decompiler and read it the way an attacker will. Glass.NET is the free, static-only companion for that pass: load the protected DLL, confirm the [GrainType("order")], [GrainInterfaceType("order")] and [Alias] strings are still present — they must be, to match the manifest — then confirm there is nothing left to read inside the renamed OrderGrain and the services it calls.

The takeaway

Orleans identifies a grain by strings — a GrainInterfaceType and a GrainType, derived by default from your .NET type names, published in the cluster manifest, and matched across silos and clients. The GrainType also prefixes every GrainId, so it keys persisted state and reminders. Rename a grain and the identity moves on a freshly built silo: the call cannot be placed and the old state is orphaned, with nothing in your code throwing. Serialization, happily, is numeric — [Id(n)] tags, not field names — so field renames are safe. Pin the identities with [GrainType], [GrainInterfaceType] and [Alias] to the values the un-obfuscated build already advertised, and the symbol is free to be destroyed: hand the entire grain interior to Nebula.NET to rename, string-encrypt and virtualize, then stand up a protected multi-silo cluster, watch the right grain activate, and read the shipped DLL to confirm the logic behind it is gone.

Try Nebula.NET

Harden your .NET code in minutes — start with the free edition.