Two of my recent Solana contributions started with values that were missing.
In one, an account filter passed validation but crashed before the SDK sent an RPC request. In the other, block response types allowed consumers to use array methods on fields that could be null or absent. Both involved a small assumption about an object's shape that did not hold for its values.
I reported the filter problem in web3.js issue #3975 and submitted PR #3977, which merged on October 9, 2026, UTC. The response-type correction is still open in web3.js PR #4014 and Kit PR #2106 as of November 2. Those last two PRs address the same metadata issue at different package boundaries.
Where the SDK sits
An RPC, or remote procedure call, lets an application query a Solana node. A client SDK converts application inputs into requests and presents responses through methods and types.
That gives the SDK two contracts to maintain: which input values it accepts, and which response values an application must handle. These contributions exposed a mismatch on each side.
The two rows describe separate APIs and failure paths before their respective fixes. A type declaration does not change the response value at runtime.
A filter key existed, but its value did not
Solana's getProgramAccounts method returns accounts owned by a program. Its filters can select accounts by data length or by bytes stored inside the account. A dataSize filter checks the total length. A memcmp, short for memory comparison, checks bytes beginning at a specified offset. The bytes field holds the encoded value to match. RPC method and filter examples
The failing input combined a usable size with an unused comparison field:
const filter = {
dataSize: 165,
memcmp: undefined,
};
"memcmp" in filter; // true: the property exists.
filter.memcmp != null; // false: there is no comparison value.
An object like this can come from a builder that always creates the same keys while leaving unused options undefined. Using null for memcmp triggered the same problem.
The SDK already validated filters by their active values. This input therefore passed as a data-size filter: dataSize had a value, and memcmp did not. Conversion then used a different rule:
- if ('memcmp' in filter) {
+ if (hasMemcmp) {
Before the fix, the property-presence check entered the comparison branch and tried to read fields such as filter.memcmp.encoding. With a nullish value, that access threw a TypeError. The valid size filter never reached the node. Conversion change
This matters when an application assembles optional filters dynamically. Account discovery or subscription setup can fail locally even though its active filter is valid. Retrying against another RPC provider would encounter the same conversion code.
My patch reuses the validated hasMemcmp condition to choose the branch. Validation and conversion now agree about which filter is active. It also preserves dataSize: 0, existing comparison encodings, and rejection of filters with two active values or no active values. A truthiness check would have introduced another problem by treating zero as absent.
The regression coverage checks both the adapter and the public getProgramAccounts, getParsedProgramAccounts, and onProgramAccountChange paths. The focused suite had 17 passing tests with the fix; eight reproduced the TypeError against the original conversion. The public request tests also check that dispatch occurs with the expected data-size filter. Patch and validation record
An array type promised more than the response
The second issue ran in the opposite direction. Block metadata could contain missing values that the SDK's public declarations did not fully describe.
The affected fields included innerInstructions, which groups calls made into other programs during transaction execution, and preTokenBalances and postTokenBalances, which describe token balances before and after execution. The inherited block types required inner-instruction arrays and excluded valid null token-balance values. Reported mismatch
For the affected declarations, a strict TypeScript consumer could trust the array type and call .map() or read .length without a guard. If the runtime value was absent, the consumer could throw while processing an otherwise valid response. In an indexer or transaction viewer, that could interrupt processing of a block. This is a consequence of the mismatch, rather than a claim that I observed a production outage.
Empty and missing data also carry different information:
| Metadata shape | What is available to the consumer |
|---|---|
innerInstructions: [] | A present array with zero entries |
innerInstructions: null | An explicit null value instead of an array |
No innerInstructions property | The field was omitted |
The reason for absence depends on the response mode and available metadata. Solana's shared response reference documents nullable metadata and fields omitted in particular modes. The declaration needs to leave those possibilities visible to callers. RPC JSON structures
A simplified type makes the consumer decision clear:
type Metadata = Readonly<{
innerInstructions?: readonly unknown[] | null;
}>;
function knownGroupCount(meta: Metadata): number | undefined {
const groups = meta.innerInstructions;
if (groups == null) return undefined;
return groups.length;
}
This example leaves out the SDK's detailed element types. The guard handles both null and undefined. A returned zero means the array was present and empty; undefined means the function could not count it.
An application can choose ?? [] when an empty collection is an appropriate fallback. For example, a screen might render no rows while reporting availability separately. That choice belongs with the application's behavior. Silently normalizing missing metadata can otherwise turn “unknown” into “zero.”
The filter fix and the metadata correction therefore use absence differently. A nullish memcmp is an inactive option under the filter validator's rules. Missing response metadata is information that the consumer may need to preserve.
Following the types across packages
I first opened the metadata issue in web3.js. On October 8, the maintainer asked me to patch Kit first so web3.js could inherit the corrected shared types through a dependency update. That led to Kit #2106. Initial maintainer response
On October 30, with the Kit PR still pending, the maintainer invited a direct web3.js patch while leaving the shared-type update for later. I opened #4014 to correct the public block boundary there. Request to proceed in web3.js
The proposed corrections make full-block inner-instruction fields optional and nullable and allow nullable token balances in the relevant full and accounts response modes. They retain the existing element types and readonly behavior. Kit also needs NonNullable before deriving an instruction element type from a now-nullable array. Kit patch
In web3.js review, the maintainer pushed a follow-up that introduced a reusable WithNullableFields helper and moved tests into the existing block-response suites with shared fixtures. That reduced repeated declarations and kept coverage beside the APIs it exercises. Maintainer follow-up
These are type corrections. They do not change runtime conversion or dependencies. Strict consumers may need new guards. Existing parsed HTTP conversion still omits null inner-instruction values; the patch does not make every response path preserve raw metadata identically. The separate getTransaction metadata declarations are outside this work. web3.js scope
A type fixture needs the compiler to run
The most useful review finding was about how the regression tests ran.
Greptile's automated review pointed out that the new type assertions were not enforced by PR CI. Unit tests ran through tsx, which removed the type checks, while declaration compilation excluded the test directory. Reverting the declaration correction could therefore leave the unit checks green. Automated review finding
I added the existing source-and-test type-check command to PR CI and the workspace type check to local just ci. The exact package command passed with the corrected declarations and produced six fixture errors against the original declarations:
pnpm --filter @solana/web3.js run test:typecheck
CI correction and regression result
The response tests and compiler fixtures answer different questions:
| Check | What it establishes |
|---|---|
| Mock HTTP and subscription responses | How the tested runtime paths handle null, omitted, and empty arrays |
| Compiler fixtures | Whether declarations accept valid shapes, reject unsafe access, and preserve element types and readonly behavior |
| Checks against the original implementation | Whether the regression coverage detects the reported defect |
The web3.js contribution recorded 54 mock response cases, along with broader unit and local validator checks. The Kit contribution used mock transports and channels in Node and browser tests; it did not run against a validator or query a live RPC. The two packages have separate validation records. web3.js validation, Kit validation
What I now check at an SDK boundary
For inputs, I check whether validation and conversion use the same definition of a usable value. A property can exist without selecting an active option, and zero can be a valid value.
For responses, I check whether the declaration covers empty, null, and omitted states before an application applies its own fallback. Then I check that the compiler actually runs against the type fixtures in CI.
These contributions changed the questions I ask during an SDK review. “Does this key exist?” and “does this field have an array type?” are only starting points. I need to follow the actual value through the boundary and verify the promise the SDK makes to its caller.
Status checked on November 2, 2026: web3.js #3977 is merged; web3.js #4014 and Kit #2106 remain open. Merge status alone does not establish which published package release includes a change.
Thanks for reading. Keep following your curiosity.