Skip to main content

IOTA Archives

An IOTA archive is a history of all transaction data on IOTA, trailing behind the latest checkpoint by 10 minutes. As an IOTA node operator, you can write this history to an object store like S3, GCS, or similar for safe keeping. Saving this archive data is considered a best practice because IOTA prunes transactions on Full nodes to remove historical transactions and their effects. Peer nodes, for example, might not catch up with all transactions and effects through synchronization if they lag behind the current epoch by more than the latest few epochs. Instead of relying on synchronization, peer nodes can fallback to downloading this information from an archive.

IOTA Archival nodes (Full nodes that write to an archive) don't store historical state on local storage and don't help query historical data. They serve the purpose of enabling peer nodes to catch up to the latest checkpoint and are useful for auditing and verifying the complete history of all transactions on the network.

Create an Archival node​

To start storing transaction history as an archive, you need to modify your node configuration. Open your fullnode.yaml file and add the following configuration. By default, the fullnode.yaml file is located in your ~/.iota/iota_config directory.

state-archive-write-config:
  object-store-config:
    object-store: "S3"
    bucket: "<bucket_name>"
    aws-access-key-id: "<AWS_ACCESS_KEY_ID>"
    aws-secret-access-key: "<AWS_SECRET_ACCESS_KEY>"
    aws-region: "<aws_region>"
    object-store-connection-limit: 20
  concurrency: 5
  use-for-pruning-watermark: false
state-archive-read-config:
  - object-store-config:
      object-store: "S3"
      # Use the same bucket which is being used in `state-archive-write-config`
      bucket: "<bucket_name>"
      aws-access-key-id: "<AWS_ACCESS_KEY_ID>"
      aws-secret-access-key: "<AWS_SECRET_ACCESS_KEY>"
      aws-region: "<aws_region>"
      object-store-connection-limit: 20
    concurrency: 5
    # This should be set to true in this case. Setting this to true
    # would prevent pruning of local transaction data until it is archived
    # in the bucket
    use-for-pruning-watermark: true

Set up archival fallback​

To enable your node to fallback to an archive in case of lag, add this to your fullnode.yaml file:

state-archive-read-config:
  - object-store-config:
      object-store: "S3"
      # Use iota-testnet-archives for testnet 
      # Use iota-mainnet-archives for mainnet
      bucket: "iota-<testnet|mainnet>-archives"
      # Use your AWS account access key id
      aws-access-key-id: "<AWS-ACCESS-KEY-ID>"
      # Use your AWS account secret access key
      aws-secret-access-key: "<AWS-SECRET-ACCESS-KEY>"
      aws-region: "<AWS-REGION>"
      object-store-connection-limit: 20
    # How many objects to read ahead when catching up  
    concurrency: 5
    # Whether to prune local state based on latest checkpoint in archive.
    # This should stay false for most use cases
    use-for-pruning-watermark: false

Even though these buckets are publicly readable, you need to make sure to properly grant the correct policies to read them via AWS, for example:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
            ],
            "Effect": "Allow",
            "Resource": [
                "arn:aws:s3:::iota-mainnet-archives/*",
                "arn:aws:s3:::iota-mainnet-archives"
            ]
        }
    ]
}

Question 1/3

What is the primary purpose of an IOTA archival node?