Update your Codama IDL

Codama's visitor system allows you to programmatically transform and enhance your IDL after creation.

Whether you started from an Anchor IDL or built from scratch, visitors let you enhance and customize the Codama IDL further before generating the clients to, for example, optimize developer experience

Essential Visitors

Visitors follow the visitor pattern, traversing your IDL nodes and applying transformations.

Let's explore the most impactful visitors for creating production-ready SDKs:

Add PDAs Visitors

To add PDA definitions to your programs, we use addPdasVisitor. This visitor is essential when your Anchor IDL doesn't include PDA information, but your program logic relies on specific Program Derived Addresses.

It accepts an object where keys are program names and values are arrays of PDA definitions to add.

codama.update(
    addPdasVisitor({
        // Add a PDA to the 'token' program.
        token: [
            {
                name: 'associatedToken',
                seeds: [
                    variablePdaSeedNode('mint', publicKeyTypeNode()),
                    constantPdaSeedNode(
                        publicKeyTypeNode(),
                        publicKeyValueNode('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA'),
                    ),
                    variablePdaSeedNode('owner', publicKeyTypeNode()),
                ],
            },
        ],
        // Add two PDAs to the 'counter' program.
        counter: [
            {
                name: 'counter',
                seeds: [variablePdaSeedNode('authority', publicKeyTypeNode())],
            },
            {
                name: 'counterConfig',
                seeds: [variablePdaSeedNode('counter', publicKeyTypeNode())],
            },
        ],
    }),
);

Update Accounts Visitor

To modify existing account definitions or remove unwanted ones, we use updateAccountsVisitor. This visitor is crucial for renaming accounts to match your preferred naming conventions or adding missing PDA associations.

You should use this when Anchor-generated account names don't match your client naming preferences, or when you need to associate PDAs with specific accounts for better code generation.

codama.update(
    updateAccountsVisitor({
        vault: {
            // Rename the 'vault' account to 'safe'.
            name: 'safe',
            // Rename the 'owner' field to 'authority'.
            data: { owner: 'authority' },
            // Create a new PDA node and link it to this account.
            seeds: [variablePdaSeedNode('authority', publicKeyTypeNode())],
        },
        counter: {
            // Delete the 'counter' account.
            delete: true,
        },
    }),
);

Update Instructions Visitor

To enhance instruction definitions with better defaults, naming, or account configurations, we use updateInstructionsVisitor. This is one of the most powerful visitors for improving the developer experience of your generated clients.

You should use this when you want to provide sensible defaults for instruction arguments, rename instructions or accounts for clarity, or mark accounts as optional to simplify client usage.

codama.update(
    updateDefinedTypesVisitor({
        options: {
            // Rename the 'options' type to 'configs'.
            name: 'configs',
            // Rename the 'sol' field to 'lamports'.
            data: { sol: 'lamports' },
        },
        player: {
            // Delete the 'player' type.
            delete: true,
        },
    }),
);

Update Defined Types Visitor

To modify custom type definitions or clean up unused types, we use updateDefinedTypesVisitor. This visitor helps maintain clean, well-named types in your generated clients.

You should use this when Anchor generates type names that don't match your preferred conventions, or when you need to remove deprecated types from your IDL.

codama.update(
    updateDefinedTypesVisitor({
        options: {
            // Rename the 'options' type to 'configs'.
            name: 'configs',
            // Rename the 'sol' field to 'lamports'.
            data: { sol: 'lamports' },
        },
        player: {
            // Delete the 'player' type.
            delete: true,
        },
    }),
);

Update Errors Visitor

To improve error definitions with clearer names, messages, or codes, we use updateErrorsVisitor. This visitor ensures your error handling is descriptive and follows consistent patterns.

You should use this when you want more descriptive error names or messages than what Anchor generates, or when you need to standardize error codes across your program suite.

codama.update(
    updateErrorsVisitor({
        invalidPda: {
            // Rename the 'invalidPda' error to 'invalidProgramDerivedAddress'.
            name: 'invalidProgramDerivedAddress',
            // Change the error message.
            message: 'The program-derived address is invalid.',
            // Change the error code.
            code: 123,
        },
        accountMismatch: {
            // Delete the 'accountMismatch' error.
            delete: true,
        },
    }),
);

Update Programs Visitor

To modify program-level information such as names, versions, or public keys, we use updateProgramsVisitor. This visitor is essential for maintaining accurate program metadata.

You should use this when you need to update program versions, standardize program names across environments, or remove deprecated programs from your IDL.

codama.update(
    updateProgramsVisitor({
        splToken: {
            // Rename the 'splToken' program to 'token'.
            name: 'token',
            // Change the program version.
            version: '3.0.0',
            // Change the program's public key.
            publicKey: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',
        },
        splAssociatedToken: {
            // Delete the 'splAssociatedToken' program.
            delete: true,
        },
    }),
);

Create your SDK with Codama