Skip to content

feat(sdk): embed the ix-mapper mapping configs in the jar and serve a mapper with no directory - #34

Closed
jpe7s wants to merge 13 commits into
mainfrom
feat/embedded-ix-mappings
Closed

jpe7s wants to merge 13 commits into
mainfrom
feat/embedded-ix-mappings

Conversation

@jpe7s

@jpe7s jpe7s commented Sep 22, 2026 •

Copy link
Copy Markdown
Member

The sdk jar now carries both v1 mapping config sets (production and staging) under glam/ix-mappings/ with a build-time index, and GlamAccounts.createMapper(factory) / GlamVaultAccounts.createMapper(invokedProgram, factory) build a mapper from them with no directory to supply. The Path overloads stay for a local set.

The sets live under one directory at the repository root, mapping/, with production/, staging/ and the provenance file SOURCE inside it; the schema version lives inside a document and in no name. The directories, mapping/production and mapping/staging, are projected one way from glamsystems/glam (its anchor_v1/ix-mapper, generated there from the managed IDL stores and gated on every PR) by that repository's public-repo sync, whose commits record the glam commit. This first import copies them by hand from glamsystems/glam#1393; once the sync leg lands (glam's sync_to_public_repos.yml, a separate PR there) the directories are written only by it. downloadMappings.sh and syncMappings.sh go, and nothing clones ix-mapper-ts any more.

Three review fixes: a protocol program the sdk does not know is refused by name rather than served staging's set (GlamEnv.ofProtocolProgram, empty for an unknown program; from keeps its meaning for state-account callers); provenance comes from the tracked mapping/SOURCE beside the sets, which the sync writes with each projection (glamsystems/glam#1396) and the build declares as an input, instead of git log; and the Stake program's authorize and withdraw keep a dropped entry for their optional lockup authority, which makes this embedding depend on an ix-proxy release carrying glamsystems/ix-mapper-java#5 (a source shorter than the index map). Bump ix-proxy to that release before marking ready.

Mutation gate: pitestSdk passes with no unaccepted survivor in EmbeddedMappings or GlamEnv; the twelve the review found were refusals the loader never exercised under test, now each covered through a loader that takes an index and a resource reader (the commit message carries the property, oracle and outcome per cluster).

EmbeddedMappings holds a set to its environment: a config whose proxy program is not one of that environment's GLAM programs is refused by name, so a production set is never served for a staging vault.

Tests: in sdk, the index names exactly the repository's files and each embedded resource holds its file's bytes, both environments hold to their own programs and refuse the other's, a narrower allowance refuses by name, and createMapper serves both environments. In services, with only the sdk on the module path, a System transfer from the vault maps onto the protocol's system_transfer with the GLAM accounts in front, in both environments, the Kamino proxies are served, a Phoenix deposit_funds built with the vault as trader maps with the vault at index 10 as a non-signer and the fee payer the only signer (glam#1393's review finding), and CCTP's token messenger is proxied by the program each deployment carries the bridge path in (ext_cctp in production, ext_bridge on staging, where deposit_for_burn maps onto cctp_deposit_for_burn). ./gradlew :sdk:check :services:check passes.

GlamAccounts also gains the staging Exponent integration program (gstgx5AbCFq4mfYKbZP23YDC7XZFUx2EURiG3PcWX6W, the declare_id of anchor_v1/programs/ext_exponent): the staging set carries an Exponent config, and the environment guard refuses a set whose proxy the accounts do not name.

The fourteen configs beyond the six each set always carried (one production, thirteen staging) are generated and gated in glam, not yet exercised against the deployed programs.

… mapper with no directory

The sdk jar already embedded the production mapping configs, materialized by a sparse
clone of the frozen ix-mapper-ts at a pinned commit, and nothing read them back: every
loader took a filesystem directory, so a service had to mount one. The two sets now live
in this repository as mapping-configs-v1 and mapping-configs-v1-staging, projected one way
from glamsystems/glam (scripts/ix-mapper-gen, generated there from the managed IDL
stores) by its public-repo sync, whose commits record the glam commit; the download and
sync scripts go. processResources embeds both sets as glam/ix-mappings/{production,staging}
beside an index the build writes, since a jar cannot be listed, and jar refuses an archive
without either set or the index.

EmbeddedMappings reads the index and the files back and holds a set to its environment:
a config whose proxy program is not one of that environment's GLAM programs is refused by
name, so a production set is never served for a staging vault. GlamAccounts.createMapper
and GlamVaultAccounts.createMapper gain overloads with no Path; the Path overloads stay for
a local set.

Tests: the index names exactly the repository's files and each embedded resource holds
its file's bytes, both environments hold to their own programs and refuse the other's, a
narrower allowance refuses by name, and createMapper serves both environments. In
services, with only the sdk on the module path, a System transfer from the vault maps
onto the protocol's system_transfer with the GLAM accounts in front, in both
environments, and the Kamino proxies are served.
GlamAccounts gains exponentIntegrationProgram beside the other integrations (builder
setter, record component, invoked and read accessors, its integration authority PDA from
the generated ExtExponentPDAs), and MAIN_NET_STAGING names ext_exponent's staging
deployment, gstgx5AbCFq4mfYKbZP23YDC7XZFUx2EURiG3PcWX6W, the declare_id in
anchor_v1/programs/ext_exponent. The embedded staging mapping set carries the Exponent
config, proxied through that program, and the environment guard refuses any config whose
proxy the accounts do not name, so the SDK had to know the program before it could serve
the set. Staging now holds fifteen integration authorities.
…_bridge

glamsystems/glam#1393 (0cdcb2be5) enrolls CCTP on staging through ext_bridge, the program
that replaces ext_cctp: the native deposit_for_burn maps onto cctp_deposit_for_burn, and
the managed handler is left out of derivation. The staging set gains that config, nineteen
files now, and the services test checks what a consumer sees: in production the token
messenger is proxied by the cctp integration program and deposit_for_burn maps onto its
handler; on staging by the bridge integration program, onto cctp_deposit_for_burn.
glamsystems/glam#1393 moves the generated sets and their config from scripts/ix-mapper-gen
to anchor_v1/ix-mapper, beside the IDL stores they derive from; the references here follow.
…faithfully

glamsystems/glam#1393 pins an idl-src-gen that derives a mapping only when the handler
reads exactly the payload the native instruction carries and every required native account
reaches the CPI target. The staging set drops the SPL stake pool (every ext_stake_pool
handler takes an extra optional argument) and, within their files, Jupiter Lend's deposit
and withdraw, Neutral's request_withdrawal, Loopscale's claim_vault_rewards, Phoenix's
register_trader and the Stake program's delegate_stake, initialize and withdraw. Eighteen
staging files; production is unchanged.
The generator now also refuses a slot the native instruction cannot fill, so Orca's
close_position_with_token_extensions leaves the staging Whirlpools config. Eighteen staging
files, production unchanged.
The Stake program's authorize and withdraw maps are one entry shorter: the trailing optional
lockup authority a client may leave out stays beyond the index map.
The no-path createMapper chose the embedded set with GlamEnv.from, which reads anything
but production as staging, so a custom protocol program was served staging's configs and
their staging proxy ids while the mapper reported the custom program as invoked. GlamEnv
gains ofProtocolProgram, empty for a program it does not know, and the embedded loader
refuses such a program by name and points at the Path overload; from keeps its meaning
for the callers that classify state accounts.
…, not git history

The index task read the glam commit from the sync commit's message with git log, which a
shallow clone lacks and an incremental build does not watch, so identical sources could
yield different provenance. ix-mappings.source, tracked at the root beside the two sets,
holds glamsystems/glam@<commit>; the sync writes it with each projection (glamsystems/glam
#1396) and the build declares it as an input, refusing a missing or malformed file. The
first import names the glam commit its sets were copied from.
… set at glam 47df4f7

The Stake program's authorize and withdraw keep a dropped entry for the optional lockup
authority again: supplied, it is dropped; left out, the mapper maps what arrives from
glamsystems/ix-mapper-java#5 on, which this embedding depends on before it merges.
…has a test

pitestSdk left twelve mutants alive in EmbeddedMappings: the loader only ever read the
real embedded resources, so none of its refusals ran under test. The loader now takes
an index and a resource reader (package-private), and each refusal has a test with its
own oracle:

Property: an index must name source, production and staging, and nothing else, or the
jar could ship half a set | Oracle: the build writes exactly those three | Outcome:
missing assertion, three tests.
Property: an indexed name is a plain <program>.json, since the loader joins it to the
set's directory | Oracle: the generator's file naming | Outcome: missing assertion.
Property: an environment with no files is refused, not served an empty mapper; a config
naming no proxy program is refused by resource name (parseConfig lets it through) |
Oracle: the class contract | Outcome: missing assertion; the proxy null-guard became a
refusal.
Property: a missing resource is refused by name | Oracle: the class contract | Outcome:
missing assertion.
Property: a set's jar directory is the lowercase environment name the build writes |
Oracle: sdk/build.gradle.kts | Outcome: missing assertion; a case-insensitive filesystem
hid the wrong case locally.

pitestSdk: 782 mutants, 744 killed, none unaccepted in EmbeddedMappings or GlamEnv.
…a name

mapping/production, mapping/staging and mapping/SOURCE: one directory for everything the
glam sync owns at this repository's root, mirroring anchor_v1/ix-mapper/mapping there. The
schema version lives inside a document (schema_version) and in no path. Every document is
byte for byte what it was; the build, its tests and the guides follow.
…ut a signer bit

Review finding on glamsystems/glam#1393: ext_phoenix takes the native accounts as remaining
accounts and requires the trader wallet to be the vault, which cannot sign, so the mapped
instruction was unsignable. The staging Phoenix set (glam facb151c6) now seats glam_vault at
the trader position with no signer bit and forwards the other native accounts in place;
the test builds a deposit_funds with the vault as trader and checks the seventeen mapped
accounts, the vault at index 10 as a non-signer, and the fee payer as the only signer.
@jpe7s
jpe7s force-pushed the feat/embedded-ix-mappings branch from a791ca5 to 6be69a7 Compare September 23, 2026 13:46
@jpe7s

jpe7s commented Sep 25, 2026

Copy link
Copy Markdown
Member Author

Superseded. ix-proxy 25.1.0 replaced the index-map configs this branch embedded with mapping documents, and main now carries that design: 8cd2936 ports the sdk onto the document mapper (GlamAccounts.createMapper over a set, GlamVaultAccounts.mappingContext), and the port of feat/mapping-document that follows it embeds the tracked ix-mapper-ts documents in the jar behind GlamAccounts.createMapper() with no directory. The one property this branch added on its own, a Phoenix deposit seating the vault as the trader without a signer bit (6be69a7), is carried by EmbeddedMapperTests there and by ix-mapper-java's conformance case phoenix-deposit-seats-the-trader-as-the-vault.

@jpe7s jpe7s closed this Sep 25, 2026
@jpe7s
jpe7s deleted the feat/embedded-ix-mappings branch September 25, 2026 16:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant