IDL does not express non-standard PDA seed encodings (e.g. i32 as decimal string)

[LongShao007]

Anchor’s IDL describes PDA seeds derived from instruction arguments by name and type, but not by how the value is encoded into bytes. For programs that use non-standard encodings (notably i32.to_string().as_bytes()), client generators infer the wrong seed format and derive incorrect PDAs.

This affects real production programs such as Orca Whirlpools.

On-chain behavior (Orca example)
In Orca Whirlpools, the tick array PDA is derived with a decimal string seed, not raw i32 bytes:

// https://github.com/orca-so/whirlpools/blob/main/programs/whirlpool/src/instructions/initialize_tick_array.rs#L16
#[account(
  init,
  payer = funder,
  seeds = [
    b"tick_array",
    whirlpool.key().as_ref(),
    start_tick_index.to_string().as_bytes(),  // UTF-8 decimal string, e.g. "-443520"
  ],
  bump,
  space = FixedTickArray::LEN,
)]
pub tick_array: AccountLoader<'info, FixedTickArray>,

For start_tick_index = -443520, the third seed is the bytes of "‑443520" (variable length), not a 4-byte little- or big-endian integer.

Correct client derivation (as used in Orca’s ecosystem and tests):

PublicKey.findProgramAddressSync(
  [
    Buffer.from("tick_array"),
    whirlpool.toBuffer(),
    Buffer.from(startTickIndex.toString()),
  ],
  programId,
);

What the Anchor IDL expresses today
When Anchor exports the IDL for this instruction, the PDA seed is typically represented only as:

• an instruction argument reference (e.g. start_tick_index)
• with type i32

The IDL does not indicate that the seed must be encoded as a UTF-8 decimal string rather than binary i32.

Downstream impact
Client code generators (e.g. Codama) read the IDL and map i32 → binary integer encoding (getI32Encoder() / 4 fixed bytes). That produces PDAs that do not match the on-chain program.

This is not limited to one generator — any tool that trusts “argument type = seed encoding” will fail for this pattern.

Orca-style programs are widespread enough that SDKs commonly ship hand-written PDA helpers instead of relying on generated ones.

Why this matters
Many CLMM programs follow the Orca pattern (to_string().as_bytes() for tick array start indices). Other DEXes use different encodings for the same logical type (e.g. Raydium CLMM uses i32 big-endian bytes). The same Rust type (i32) can map to incompatible seed bytes, but the IDL gives clients no way to distinguish them.

Suggested direction
Consider extending the IDL so PDA seeds can declare encoding explicitly, for example:

{
  "kind": "arg",
  "path": "start_tick_index",
  "type": "i32",
  "encoding": "utf8_decimal_string"
}

Or another machine-readable form that covers:

• raw fixed-size integers (le / be)
• UTF-8 decimal strings (Orca-style)
• other common patterns

Without this, Anchor IDL is incomplete for a valid and common Anchor pattern (seeds = [..., arg.to_string().as_bytes()]), and client generators cannot produce correct PDA helpers from the IDL alone.

Environment

• Pattern observed in: Orca Whirlpools initialize_tick_array (source)
• Impact: incorrect PDA derivation in Codama-generated clients unless overridden manually

[jamie-osec]

For reference, IDL changes now need to go through https://github.com/solana-foundation/idl-spec/

[Ysh204]

I ran into the same limitation while working on Anchor's IDL generator and arrived at essentially the same conclusion.

I implemented a proof-of-concept end-to-end that:

• extends IdlSeedArg with an optional encoding field,
• detects common non-default seed encodings such as:
  • arg.to_string().as_bytes()
  • arg.to_be_bytes()
• keeps little-endian implicit for backwards compatibility,
• updates the TypeScript client to respect the declared encoding when deriving PDA seeds,
• and adds end-to-end integration tests covering these cases.

The implementation passes the existing Rust and TypeScript test suites, along with new PDA derivation tests for UTF-8 decimal string and big-endian integer encodings.

That work was originally submitted in #4735, but the PR was closed because IDL specification changes are now handled in this repository instead.

One thing I found while implementing this is that the issue is broader than UTF-8 decimal strings alone. Different programs intentionally use different byte encodings for the same Rust type (for example, little-endian, big-endian, or decimal UTF-8), so the Rust type alone is not sufficient for deterministic PDA derivation.

I'm happy to adapt the implementation to whatever representation the specification prefers. Whether that's an explicit encoding field or another machine-readable representation, I think the important property is that the IDL fully describes the seed bytes so independent tooling can deterministically derive the same PDA as the on-chain program.

[LongShao007]

Thanks for pointing that out — I wasn’t aware IDL changes now go through the idl-spec repo. That does add a fair bit of overhead.

For context, our issue is around deriving tick array PDAs on the client side (e.g. getTickArrayPda), and it’s not entirely clear whether this belongs in the IDL spec layer, Anchor’s client codegen, or somewhere else entirely.

What’s the recommended path to raise this with the Anchor team? Should we open an issue on solana-foundation/anchor, or is there a different channel (Discord, RFC, etc.) for this kind of discussion?

A quick outline of how Anchor typically triages these — especially when it might touch both client tooling and the broader IDL spec — would be really helpful.

[Ysh204]

From what I've seen, the Anchor maintainers are moving IDL evolution into the solana-foundation/idl-spec repository.

When I opened the Anchor PR implementing this (otter-sec/anchor#4735), the feedback I received was:

"Changes to the IDL specification should now go through https://github.com/solana-foundation/idl-spec/"

So my understanding is that the specification should be discussed there first. Once there's agreement on the shape of the IDL, the corresponding implementation can then be made in Anchor.

I don't know if there's a separate RFC or Discord process beyond what's documented in the idl-spec repository, so I wouldn't want to speculate. If there is, hopefully one of the maintainers can point us to it.

In any case, I think your issue demonstrates why this belongs at the specification level: today the IDL doesn't fully describe the bytes used for PDA derivation, which means independent tooling can't deterministically derive the same PDA for all valid Anchor programs.