Files
khadhroony-bot3/test-fixtures/contract-matrices/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json
2026-08-09 22:48:31 +02:00

218 lines
21 KiB
JSON

{
"file": "docs/SPL_ASSOCIATED_TOKEN_ACCOUNT_MATRIX.json",
"version": 11,
"schemaVersion": 1,
"bot3Migration": {
"target": "ks-lib-decoder.spl.associated_token_account",
"status": "decoder_operator_validated_materializers_ported",
"prerelease": "0.1.0-pre.007",
"preservedDifferentialTests": 10,
"materializerPorted": true,
"publicMaterializers": [
"ks_lib::TokenAccountsMaterializer",
"ks_lib::RiskMaterializer"
],
"executorPorted": false,
"pipelinePorted": false
},
"programId": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
"systemProgramId": "11111111111111111111111111111111",
"supportedTokenPrograms": [
{"code": "spl.token", "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "scope": "classic_token_account_lifecycle_only"},
{"code": "spl.token_2022", "programId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb", "scope": "ata_lifecycle_only_without_general_token_2022_instruction_or_extension_decode"}
],
"interface": {
"workspaceConstraint": "^2.0",
"resolvedVersion": "2.0.0",
"resolutionEvidence": "docs_rs_latest_published_version_and_official_interface_tag",
"workspaceCargoResolutionStatus": "confirmed_by_operator_cargo_tree_2026-07-16",
"features": ["borsh"],
"bincodeEnabled": false,
"officialTag": "interface@v2.0.0",
"releaseCommit": "250da0e21a9853a7afddba85658ed8a9119c71c9",
"releaseDate": "2025-08-08",
"instructionSource": "https://github.com/solana-program/associated-token-account/blob/interface@v2.0.0/interface/src/instruction.rs",
"addressSource": "https://github.com/solana-program/associated-token-account/blob/interface@v2.0.0/interface/src/address.rs",
"publishedDocumentation": "https://docs.rs/spl-associated-token-account-interface/2.0.0/spl_associated_token_account_interface/"
},
"processor": {
"auditedRelease": "program@v8.0.0",
"releaseCommit": "0b867b5",
"releaseDate": "2025-10-29",
"source": "https://github.com/solana-program/associated-token-account/blob/program@v8.0.0/program/src/processor.rs",
"deploymentBinaryEquality": {"localnet": "not_tested", "devnet": "not_proven", "mainnet": "not_proven"},
"note": "Interface publication, processor source, cluster deployment and successful execution are tracked independently."
},
"wire": {
"format": "Borsh enum with unit variants encoded as one u8 ordinal",
"strictSuffixPolicy": "reject",
"legacyEmptyCreate": {"decodeSupport": true, "builderEmits": false, "encodingHex": "", "status": "historical_runtime_and_transaction_parser_compatibility_to_be_reconfirmed_by_cluster_corpus"},
"unknownOrTruncatedPolicy": "bounded diagnostic without lifecycle projection"
},
"pdaDerivation": {
"programId": "ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL",
"seedOrder": ["wallet_address_bytes[32]", "token_program_id_bytes[32]", "mint_address_bytes[32]"],
"algorithm": "Pubkey::find_program_address",
"validationPolicy": "preserve observed address and report exact match or mismatch; never replace an observed account silently",
"differentialVectors": [
{"wallet": "11111111111111111111111111111111", "mint": "So11111111111111111111111111111111111111112", "tokenProgramId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "expectedAta": "aqxoAhCwpy3oB1BpNw9hL1HdLYLgPpbPjzxDrrQj3Fs", "expectedBump": 254, "evidence": "PublicKey.findProgramAddressSync with the canonical official seed order"},
{"wallet": "11111111111111111111111111111111", "mint": "So11111111111111111111111111111111111111112", "tokenProgramId": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb", "expectedAta": "2sZUUBGq1i6aE47ZoxCaCW89jmYm2EXLPPmNMgMDXHMS", "expectedBump": 250, "evidence": "PublicKey.findProgramAddressSync with the canonical official seed order"}
]
},
"limits": {"exactVariantCount": 3, "createRequiredAccountCount": 6, "recoverNestedRequiredAccountCount": 7, "maximumDiagnosticBytes": 256, "extraAccounts": "preserved_and_reported; never assigned an invented role"},
"executionPreflight": {
"clusters": ["localnet", "devnet"],
"programIds": ["associated_token_program", "selected_token_program", "system_program_for_creation"],
"stateChecks": ["mint_exists_initialized_and_owned_by_selected_token_program", "canonical_pda_derivation", "strict_create_absence", "idempotent_absence_or_existing_account_compatibility", "recover_nested_three_account_relationships", "required_signers_available", "payer_balance_covers_rent_plus_fee_ceiling"],
"token_2022Boundary": "base Mint and Token Account prefixes are validated while suffix extensions remain opaque; simulation determines extension-dependent runtime acceptance and exact account size",
"simulation": "required_before_signing_or_sending",
"defaultMode": "dry_run"
},
"surfaceEquality": {"matrixVariantCount": 3, "officialInterfaceVariantCount": 3, "compiledDecoderCoverageStatus": "three_exact_compiled_instruction_declarations_operator_validated", "compiledExecutorCapabilityStatus": "three_exact_current_capabilities_operator_validated", "requiredFinalInvariant": "matrix == official interface enum == decoder coverage == executor capability declarations"},
"instructions": [
{
"name": "create",
"discriminant": 0,
"canonicalEncodingHex": "00",
"acceptedDecodeEncodingsHex": ["", "00"],
"status": "current_with_legacy_empty_wire_compatibility",
"accounts": [
{"position": 0, "role": "funding_account", "signer": true, "writable": true, "expectedProgram": "system_account"},
{"position": 1, "role": "associated_token_account", "signer": false, "writable": true, "expectedProgram": "derived_pda_before_creation_or_supported_token_program_after_creation"},
{"position": 2, "role": "wallet_owner", "signer": false, "writable": false, "expectedProgram": "unconstrained_wallet_address"},
{"position": 3, "role": "mint", "signer": false, "writable": false, "expectedProgram": "account_owned_by_token_program_at_runtime"},
{"position": 4, "role": "system_program", "signer": false, "writable": false, "expectedAddress": "11111111111111111111111111111111"},
{"position": 5, "role": "token_program", "signer": false, "writable": false, "allowedAddresses": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"]}
],
"addressRules": ["associated_token_account = PDA(wallet_owner, token_program, mint)", "observed associated_token_account is retained on mismatch"],
"tokenProgramDifferences": {"classic": "create and initialize a classic token account", "token_2022": "size is obtained from the Token-2022 mint and immutable-owner initialization is performed before account initialization; extensions themselves remain out of decoder scope"},
"runtimeRules": ["fails if the associated account already exists", "funding account pays rent and creation cost", "mint and created account must be coherent with the selected token program"],
"event": "spl.associated_token_account.create",
"authorizedProjections": ["token_accounts:ata_created"],
"forbiddenProjections": ["token_balance_snapshot", "duplicate_spl_token_initialize_account_cpi", "token_2022_extension_fact"],
"officialBuilder": {"available": true, "function": "create_associated_token_account", "canonicalWireOnly": true},
"executorSupport": {"status": "supported", "operationCode": "spl.associated_token_account.create", "builder": "create_associated_token_account", "simulation": "required", "defaultMode": "dry_run"},
"proofs": {"synthetic": ["canonical_00", "legacy_empty", "classic_token_program", "token_2022_program", "wrong_ata", "missing_account", "extra_account", "duplicate_account", "wrong_flags", "unknown_suffix", "outer", "inner_cpi", "committed", "failed_intent"], "localnet": "not_tested", "devnet": "not_tested", "mainnetSignatures": []}
},
{
"name": "create_idempotent",
"discriminant": 1,
"canonicalEncodingHex": "01",
"acceptedDecodeEncodingsHex": ["01"],
"status": "current",
"accounts": [
{"position": 0, "role": "funding_account", "signer": true, "writable": true, "expectedProgram": "system_account"},
{"position": 1, "role": "associated_token_account", "signer": false, "writable": true, "expectedProgram": "derived_pda_or_supported_token_program"},
{"position": 2, "role": "wallet_owner", "signer": false, "writable": false},
{"position": 3, "role": "mint", "signer": false, "writable": false},
{"position": 4, "role": "system_program", "signer": false, "writable": false, "expectedAddress": "11111111111111111111111111111111"},
{"position": 5, "role": "token_program", "signer": false, "writable": false, "allowedAddresses": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"]}
],
"addressRules": ["associated_token_account = PDA(wallet_owner, token_program, mint)", "existing account must retain the selected token program, wallet owner and mint"],
"tokenProgramDifferences": {"classic": "existing classic account is accepted only when owner and mint match", "token_2022": "existing Token-2022 account is accepted only when owner and mint match; no extension semantics are inferred"},
"runtimeRules": ["creates when absent", "succeeds without recreating when an initialized compatible ATA already exists", "fails when an existing account has a different wallet owner, mint or account owner program"],
"event": "spl.associated_token_account.create_idempotent",
"authorizedProjections": ["token_accounts:ata_created_or_reused_idempotently"],
"forbiddenProjections": ["token_balance_snapshot", "duplicate_spl_token_initialize_account_cpi", "token_2022_extension_fact"],
"officialBuilder": {"available": true, "function": "create_associated_token_account_idempotent", "canonicalWireOnly": true},
"executorSupport": {"status": "supported", "operationCode": "spl.associated_token_account.create_idempotent", "builder": "create_associated_token_account_idempotent", "simulation": "required", "defaultMode": "dry_run"},
"proofs": {"synthetic": ["canonical_01", "absent_account", "compatible_existing_account", "conflicting_existing_owner", "conflicting_existing_mint", "conflicting_existing_program", "classic_token_program", "token_2022_program", "wrong_ata", "wrong_flags", "unexpected_suffix", "outer", "inner_cpi", "committed", "failed_intent"], "localnet": "not_tested", "devnet": ["5Vw4QFpMa8oJ8MsLrvDg4RFzxqUh27mTFRFzzwJFoA4uAry8rZQc6GP92aidzWugn3CeZ5NYNxDp7tZ6bh8XyN1P", "2H9VfhDySdXMteazm2P3s2fTttJBQzMJinQtKqsLtkjDg7zbFFgiWG81UxRQF4va3bbR2pUV4QGo2qErisR8CPbP", "3wWTkx45LoDR3UaU8VUfsWxwHuLFyJyhrnDrmijCa7pXPdmJKz3rQ1LdyDvb78dvNRiKqw5ee7HuZ6Gjj1Gpfv6q", "bMMjoHcwbaTvLXerdQ4kbGXGb7wydiTyvSEwwmoKKLQcRWWBzqGUMYHZztonNnER1iWZ7yKp9p3neeMhypX4QAJ", "4RZKA3KwEbSqgU8UnemTgvd3fBgJmoSK2nmaaTNP8nJGTVh6DrFwrHVZYCBvLFvhvzUdi9p1KRFe4hHqYt7JbVSG"], "mainnetSignatures": ["2F9RvuCkevfJN7ju252hAWoCE58wagCXCWHQF9Wsdtsxvp3HcuNJQFCwU7zGqe3z3b8pv3vPp4xY5EH7KLcaHQCY"], "realCorpusStatus": "controlled classic and Token-2022 CreateIdempotent creation then compatible-existing reuse confirmed, materialized once per signature and replayed idempotently; search-discovered Token-2022 outer transaction remains additional corpus"}
},
{
"name": "recover_nested",
"discriminant": 2,
"canonicalEncodingHex": "02",
"acceptedDecodeEncodingsHex": ["02"],
"status": "current_recovery_operation",
"accounts": [
{"position": 0, "role": "nested_associated_token_account", "signer": false, "writable": true},
{"position": 1, "role": "nested_mint", "signer": false, "writable": false},
{"position": 2, "role": "wallet_nested_mint_associated_token_account", "signer": false, "writable": true},
{"position": 3, "role": "owner_associated_token_account", "signer": false, "writable": false},
{"position": 4, "role": "owner_mint", "signer": false, "writable": false},
{"position": 5, "role": "wallet_owner", "signer": true, "writable": true},
{"position": 6, "role": "token_program", "signer": false, "writable": false, "allowedAddresses": ["TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb"]}
],
"addressRules": ["owner_associated_token_account = PDA(wallet_owner, token_program, owner_mint)", "nested_associated_token_account = PDA(owner_associated_token_account, token_program, nested_mint)", "wallet_nested_mint_associated_token_account = PDA(wallet_owner, token_program, nested_mint)"],
"tokenProgramDifferences": {"classic": "transfer the complete nested balance and close the nested classic token account", "token_2022": "same ATA address relationships through Token-2022 CPIs; extension-specific transfer or close restrictions can prevent recovery and are not decoded as ATA facts"},
"runtimeRules": ["all three derived addresses must match their observed accounts", "owner and nested token accounts must be initialized and coherent with their respective mints", "wallet owner must sign", "complete nested token balance is moved to the wallet destination ATA", "nested account is closed and its lamports are returned to the wallet"],
"event": "spl.associated_token_account.recover_nested",
"authorizedProjections": ["token_accounts:nested_ata_recovered", "risk:nested_ata_anti_pattern_recovered"],
"forbiddenProjections": ["duplicate_spl_token_transfer_cpi", "duplicate_spl_token_close_account_cpi", "token_balance_snapshot", "token_2022_extension_fact"],
"officialBuilder": {"available": true, "function": "recover_nested", "canonicalWireOnly": true},
"executorSupport": {"status": "supported", "operationCode": "spl.associated_token_account.recover_nested", "builder": "recover_nested", "simulation": "required", "defaultMode": "dry_run"},
"proofs": {"synthetic": ["canonical_02", "classic_token_program", "token_2022_program", "valid_three_pda_relationships", "wrong_nested_ata", "wrong_destination_ata", "wrong_owner_ata", "owner_and_nested_mints_not_inverted", "missing_account", "extra_account", "duplicate_account", "wrong_flags", "unexpected_suffix", "outer", "inner_cpi", "committed", "failed_intent"], "localnet": "not_tested", "devnet": ["37LG6GdMRp5ECG8qf1RSYxmriJk75UtCwqwzXZWpArebkKo6BQvGhYEnbDh2A6KWiUaHK28Zy1gGGZ5zihvrHskM"], "mainnetSignatures": [], "realCorpusStatus": "controlled classic RecoverNested confirmed with positive raw balance transfer, nested ATA closure, owner and destination post-validation, two distinct ATA lifecycle and risk projections, and idempotent second replay", "controlledDevnetFixture": {"walletOwner": "DwuAapPLg6pEJ4QhmxvPg8rzkavmYdg5FW4dfEMcg8B2", "ownerMint": "So11111111111111111111111111111111111111112", "ownerAssociatedTokenAccount": "3tdXq1W7vEbbkxQmT1r2fc349uYti98zpwLKhp7FFbF5", "nestedMint": "3fd5CqP1w4Y1xeMoAe3apA7Jf5SbL3vboxv7ihyXhC9A", "nestedAssociatedTokenAccount": "AAyvGeKpq6i3kxMcScJLcN2u5iyAsspr731LhgXygti5", "walletNestedMintAssociatedTokenAccount": "69TP2QoSx2inueFAEb6npjumH5o3wGJQDSwwAJLLfyWp", "rawAmountTransferred": "1000000000", "nestedAccountClosed": true, "destinationUiBalanceAfter": "1", "materializedOutputCount": 2}}
}
],
"offlineCorpus": {
"status": "implemented_and_operator_validated_in_decoder_unit_tests",
"wire": ["create_00", "legacy_empty_create", "create_idempotent_01", "recover_nested_02", "unknown_tag", "rejected_suffix"],
"tokenPrograms": ["spl_token_classic", "token_2022"],
"locations": ["outer", "inner_cpi"],
"transactionOutcomes": ["committed", "failed_uncommitted_intent"],
"accountShapes": ["canonical", "missing", "extra", "duplicate", "wrong_flags", "wrong_derived_address", "unsupported_token_program", "wrong_system_program"],
"derivation": ["create_single_pda", "recover_nested_three_independent_pda_relationships", "official_helper_differential_vectors"],
"limits": "diagnostic count and payload prefix are bounded; no arbitrary payload or account repair"
},
"materializationContract": {
"committedOnly": true,
"idempotenceIdentity": "signature + instruction_path + program_id + normalized_operation + ata",
"projectionOwners": [
{
"crate": "ks-lib",
"component": "materializer.token.accounts",
"facts": [
"ata_created",
"ata_created_or_reused_idempotently",
"nested_ata_recovered"
],
"justification": "ATA creation and recovery are stable token-account lifecycle facts; this crate already owns instruction-level token-account mutations."
},
{
"crate": "ks-lib",
"component": "materializer.risk",
"facts": [
"nested_ata_anti_pattern_recovered"
],
"justification": "A committed RecoverNested proves the distinct stable risk fact that a nested ATA anti-pattern existed and was recovered; no score or speculative severity is added."
}
],
"explicitNoProjection": [
{
"crate": "ks-lib",
"component": "materializer.lifecycle",
"reason": "Native program lifecycle remains owned here; duplicating ATA lifecycle would overlap the token-account materializer."
},
{
"crate": "ks-lib",
"component": "materializer.admin",
"reason": "ATA instructions do not change a mint authority, freeze authority, close authority or multisig configuration."
},
{
"crate": "ks-lib",
"component": "materializer.fees",
"reason": "ATA wire does not prove an exact rent or network-fee amount; core balance changes and execution validation retain those facts."
}
],
"implementationStatus": "pre_004 executor and stateful preflight operator validated; pre_005 classic and Token-2022 CreateIdempotent Devnet orchestration plus Tauri validated; pre_006 classic RecoverNested Devnet orchestration validated",
"idempotentOutcomeLimit": "CreateIdempotent parent proves successful ensure semantics but cannot distinguish created from reused without sibling CPI correlation; the projection preserves created_or_reused and invents neither boolean.",
"parentChildOwnership": "ATA parent owns only associated-address lifecycle and the distinct nested-ATA risk fact; SPL Token or Token-2022 CPI observations own token initialize, transfer and close mutations.",
"noSnapshotClaim": true,
"databaseMigrationStatus": "not_justified"
},
"executionContract": {"simulationRequired": true, "dryRunDefault": true, "clusterPolicyOwnedByCommonLayers": true, "rentAndFeeCeilingRequired": true, "signerDeduplicationDoesNotChangeMetaOrder": true, "confirmedStateReadRetryBound": 20, "canonicalHydrationRpcRetryBoundPerAttempt": 2, "postValidation": {"create": "ATA exists, is owned by selected token program, and contains expected wallet owner and mint", "createIdempotent": "same invariant whether the ATA was created or reused", "recoverNested": "owner ATA and destination remain coherent, nested ATA is absent, and no balance value is invented by ATA projection"}},
"deploymentAudit": {
"localnet": {"status": "not_tested", "evidence": []},
"devnet": {"status": "classic and Token-2022 CreateIdempotent creation and compatible-existing reuse confirmed; classic RecoverNested positive-balance recovery confirmed", "evidence": ["5Vw4QFpMa8oJ8MsLrvDg4RFzxqUh27mTFRFzzwJFoA4uAry8rZQc6GP92aidzWugn3CeZ5NYNxDp7tZ6bh8XyN1P", "2H9VfhDySdXMteazm2P3s2fTttJBQzMJinQtKqsLtkjDg7zbFFgiWG81UxRQF4va3bbR2pUV4QGo2qErisR8CPbP", "3wWTkx45LoDR3UaU8VUfsWxwHuLFyJyhrnDrmijCa7pXPdmJKz3rQ1LdyDvb78dvNRiKqw5ee7HuZ6Gjj1Gpfv6q", "bMMjoHcwbaTvLXerdQ4kbGXGb7wydiTyvSEwwmoKKLQcRWWBzqGUMYHZztonNnER1iWZ7yKp9p3neeMhypX4QAJ", "4RZKA3KwEbSqgU8UnemTgvd3fBgJmoSK2nmaaTNP8nJGTVh6DrFwrHVZYCBvLFvhvzUdi9p1KRFe4hHqYt7JbVSG", "37LG6GdMRp5ECG8qf1RSYxmriJk75UtCwqwzXZWpArebkKo6BQvGhYEnbDh2A6KWiUaHK28Zy1gGGZ5zihvrHskM"], "controlledToken2022Fixture": {"mint": "3DxKAUfCZkR9oRfMXeRNpiVL464eKbTieymBrVhsoKTE", "mintOwner": "TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb", "mintBaseLength": 82, "walletOwner": "DwuAapPLg6pEJ4QhmxvPg8rzkavmYdg5FW4dfEMcg8B2", "associatedTokenAccount": "6WfCJPt7GZQyMJAUS1AMHJrD7Vid8e9xUEQVgi5Q9C9Y", "accountLength": 170, "accountExtension": "immutable_owner", "creationSlot": 476702448, "existingReuseSlot": 476703343}},
"mainnet": {"status": "search_discovered_token_2022_create_idempotent_not_yet_replayed", "evidence": ["2F9RvuCkevfJN7ju252hAWoCE58wagCXCWHQF9Wsdtsxvp3HcuNJQFCwU7zGqe3z3b8pv3vPp4xY5EH7KLcaHQCY"]},
"rateLimitRecovery": "preserve confirmed signatures and resume bounded hydration; never recreate accounts blindly after HTTP 429"
},
"nonClaims": [
"No general Token-2022 instruction or extension decoding is implemented in 0.4.5.",
"No Token balance or final account snapshot is reconstructed from ATA instructions.",
"No cluster binary equality is inferred from interface publication.",
"The controlled Token-2022 proof covers ATA lifecycle only and does not claim general Token-2022 instruction or extension decoding.",
"No dedicated SQL table is justified by this audit tranche."
]
}