Northern Pileated Marmoset

    @metaplex-foundation/amman
    TypeScript icon, indicating that this package has built-in type declarations

    0.12.1 • Public • Published

    Amman

    A m odern man datory toolbelt to help test solana SDK libraries and apps on a locally running validator.

    Table of Contents generated with DocToc

    API

    Aside from providing a CLI for various tasks, amman also provides commonly used actions, transactions, asserts and more via an API. Please find the API docs here.

    CLI

    amman [command]
    
    Commands:
      amman start    Launches a solana-test-validator and the amman relay and/or
                     mock storage if so configured
      amman stop     Stops the relay and storage and kills the running solana
                     test validator
      amman logs     Launches 'solana logs' and pipes them through a prettifier
      amman airdrop  Airdrops provided Sol to the payer
      amman label    Adds labels for accounts or transactions to amman
      amman account  Retrieves account information for a PublicKey or a label or
                     shows all labeled accounts
      amman run      Executes the provided command after expanding all address
                     labels
    
    Options:
      --help     Show help                                                 [boolean]
      --version  Show version number                                       [boolean]

    Commands: start

    amman start <config.js>

    If no config.js is provided amman looks for an .ammanrc.js file in the current directory. If that isn't found either it uses a default config.

    The config should be a JavaScript module exporting 'validator' with any of the below properties:

    • killRunningValidators: if true will kill any solana-test-validators currently running on the system.
    • programs: bpf programs which should be loaded into the test validator
    • accountsCluster: default cluster to clone remote accounts from
    • accounts: array of remote accounts to load into the test validator
    • jsonRpcUrl: the URL at which the test validator should listen for JSON RPC requests
    • websocketUrl: for the RPC websocket
    • ledgerDir: where the solana test validator writes the ledger
    • resetLedger: if true the ledger is reset to genesis at startup
    • verifyFees: if true the validator is not considered fully started up until it charges transaction fees

    Example Configs

    Validator/Relay/Storage Config with Defaults

    Below is an example config with all values set to the defaults except for an added program and a relay and storage config.

    A amman-explorer relay is launched automatically with the validator unless it is running in a CI environment and if a relay is already running on the known relay port, it is killed first.

    A mock storage is launched only if a storage config is provided. In case a storage server is already running on the known storage port, it is killed first.

    import { LOCALHOST, tmpLedgerDir } from '@metaplex-foundation/amman'
    
    module.exports = {
      validator: {
        killRunningValidators: true,
        programs: [
          { 
            label: 'Token Metadata Program',
            programId: programIds.metadata,
            deployPath: localDeployPath('mpl_token_metadata')
          },
        ],
        jsonRpcUrl: LOCALHOST,
        websocketUrl: '',
        commitment: 'confirmed',
        ledgerDir: tmpLedgerDir(),
        resetLedger: true,
        verifyFees: false,
        detached: process.env.CI != null,
      },
      relay: {
        enabled: process.env.CI == null,
        killlRunningRelay: true,
      },
      storage: {
        enabled: process.env.CI == null,
        storageId: 'mock-storage',
        clearOnStart: true,
      },
    }

    Config with Remote Accounts

    Below is an example of a config where the accounts are being pulled from a specific RPC endpoint.

    module.exports = {
      validator: {
        // By default Amman will pull the account data from the accountsCluster (can be overridden on a per account basis)
        accountsCluster: 'https://api.metaplex.solana.com',
        accounts: [
            {
              label: 'Token Metadata Program',
              accountId:'metaqbxxUerdq28cj1RbAWkYQm3ybzjb6a8bt518x1s',
              // marking executable as true will cause Amman to pull the executable data account as well automatically
              executable: true,
            },
            {
              label: 'Random other account',
              accountId:'4VLgNs1jXgdciSidxcaLKfrR9WjATkj6vmTm5yCwNwui',
              // By default executable is false and is not required to be in the config
              // executable: false,
              
              // Providing a cluster here will override the accountsCluster field
              cluster: 'https://metaplex.devnet.rpcpool.com'
            }
          ]
      }
    }

    Deactivating Test Validator Features

    For the different clusters like devnet some features are disabled. By default the locally running solana-test-validator does not disable any features and thus behaves differently than the provided clusters.

    In order to run tests in a scenario that is closer to how they would run against a specific cluster you can match the features of it via the matchFeatures config property:

    module.exports = {
      validator: {
        ...
        // The below disables any features that are deactivated for the `mainnet-beta` cluster
        matchFeatures: 'mainnet-beta',
      }
    }

    If you want to explicitly disable a set of features you can do so via the deactivateFeatures property:

    module.exports = {
      validator: {
        ...
       deactivateFeatures: ['21AWDosvp3pBamFW91KB35pNoaoZVTM7ess8nr2nt53B'],
      }
    }

    NOTE: that only one of the above properties can be set

    Resources

    LICENSE

    Apache-2.0

    Install

    npm i @metaplex-foundation/amman

    DownloadsWeekly Downloads

    6,857

    Version

    0.12.1

    License

    Apache-2.0

    Unpacked Size

    340 kB

    Total Files

    155

    Last publish

    Collaborators

    • 0x_febo
    • stegabob
    • svc01-metaplex
    • samuelvanderwaal
    • brandontulsi
    • lorisleiva
    • roederw
    • thlorenz
    • austbotm