{"_id":"@atlaschain/transaction-confirmation","name":"@atlaschain/transaction-confirmation","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@atlaschain/transaction-confirmation","version":"3.0.0","description":"Helpers for confirming Atlas transactions","exports":{"edge-light":{"import":"./dist/index.node.mjs","require":"./dist/index.node.cjs"},"workerd":{"import":"./dist/index.node.mjs","require":"./dist/index.node.cjs"},"browser":{"import":"./dist/index.browser.mjs","require":"./dist/index.browser.cjs"},"node":{"import":"./dist/index.node.mjs","require":"./dist/index.node.cjs"},"react-native":"./dist/index.native.mjs","types":"./dist/types/index.d.ts"},"browser":{"./dist/index.node.cjs":"./dist/index.browser.cjs","./dist/index.node.mjs":"./dist/index.browser.mjs"},"main":"./dist/index.node.cjs","module":"./dist/index.node.mjs","react-native":"./dist/index.native.mjs","types":"./dist/types/index.d.ts","type":"commonjs","sideEffects":false,"keywords":["blockchain","atlas","web3"],"author":{"name":"Atlas Chain Foundation"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/anza-xyz/kit.git"},"bugs":{"url":"https://github.com/anza-xyz/kit/issues"},"browserslist":["supports bigint and not dead","maintained node versions"],"dependencies":{"@atlaschain/addresses":"3.0.0","@atlaschain/codecs-strings":"3.0.0","@atlaschain/promises":"3.0.0","@atlaschain/rpc":"3.0.0","@atlaschain/errors":"3.0.0","@atlaschain/rpc-subscriptions":"3.0.0","@atlaschain/rpc-types":"3.0.0","@atlaschain/transactions":"3.0.0","@atlaschain/transaction-messages":"3.0.0","@atlaschain/keys":"3.0.0"},"peerDependencies":{"typescript":">=5.3.3"},"engines":{"node":">=20.18.0"},"scripts":{"compile:docs":"typedoc","compile:js":"tsup --config build-scripts/tsup.config.package.ts","compile:typedefs":"tsc -p ./tsconfig.declarations.json","dev":"jest -c ../../node_modules/@atlaschain/test-config/jest-dev.config.ts --rootDir . --watch","publish-packages":"npm view $npm_package_name@$npm_package_version > /dev/null 2>&1 || (pnpm publish --tag ${PUBLISH_TAG:-canary} --access public --no-git-checks && (([ -n \"${GITHUB_OUTPUT:-}\" ] && echo 'published=true' >> \"$GITHUB_OUTPUT\") || true) && (([ \"$PUBLISH_TAG\" != \"canary\" ] && pnpm dist-tag add $npm_package_name@$npm_package_version latest) || true))","style:fix":"pnpm eslint --fix src && pnpm prettier --log-level warn --ignore-unknown --write ./*","test:lint":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlaschain/test-config/jest-lint.config.ts --rootDir . --silent","test:prettier":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlaschain/test-config/jest-prettier.config.ts --rootDir . --silent","test:treeshakability:browser":"agadoo dist/index.browser.mjs","test:treeshakability:native":"agadoo dist/index.native.mjs","test:treeshakability:node":"agadoo dist/index.node.mjs","test:typecheck":"tsc --noEmit","test:unit:browser":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlaschain/test-config/jest-unit.config.browser.ts --rootDir . --silent","test:unit:node":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlaschain/test-config/jest-unit.config.node.ts --rootDir . --silent"},"_id":"@atlaschain/transaction-confirmation@3.0.0","homepage":"https://github.com/anza-xyz/kit#readme","_integrity":"sha512-r5xjmxpjbb1T7hO6VtKC6sgJMu2PIWH/lBDX/RFOMDnBB7aGnrQZKCgvvCjZw/MpFLBe7Oj2mHV3VY0iHmjAYA==","_resolved":"/private/var/folders/q8/nr55p0wd491c6fjmbky17kd00000gn/T/e515dea62f74b732ea98e42addc33091/atlaschain-transaction-confirmation-3.0.0.tgz","_from":"file:atlaschain-transaction-confirmation-3.0.0.tgz","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-r5xjmxpjbb1T7hO6VtKC6sgJMu2PIWH/lBDX/RFOMDnBB7aGnrQZKCgvvCjZw/MpFLBe7Oj2mHV3VY0iHmjAYA==","shasum":"b554df01e95c36fbdb2ac9ec2239775112a48891","tarball":"https://registry.npmjs.org/@atlaschain/transaction-confirmation/-/transaction-confirmation-3.0.0.tgz","fileCount":5,"unpackedSize":19426,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAqib5nZhPl7S4WvZyZ7dT4tL2zHMqjZH3DwKsZGgAdwAiBVVric7barAKvcO9H3x31a5PsmSebW5vjOhmRvrAr65A=="}]},"_npmUser":{"name":"atlaschain","email":"jq@atlaschain.org"},"directories":{},"maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/transaction-confirmation_3.0.0_1764611554923_0.1875813440124221"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-01T17:52:34.860Z","3.0.0":"2025-12-01T17:52:35.113Z","modified":"2025-12-01T17:52:35.399Z"},"maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"description":"Helpers for confirming Atlas transactions","homepage":"https://github.com/anza-xyz/kit#readme","keywords":["blockchain","atlas","web3"],"repository":{"type":"git","url":"git+https://github.com/anza-xyz/kit.git"},"author":{"name":"Atlas Chain Foundation"},"bugs":{"url":"https://github.com/anza-xyz/kit/issues"},"license":"MIT","readme":"[![npm][npm-image]][npm-url]\n[![npm-downloads][npm-downloads-image]][npm-url]\n<br />\n[![code-style-prettier][code-style-prettier-image]][code-style-prettier-url]\n\n[code-style-prettier-image]: https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square\n[code-style-prettier-url]: https://github.com/prettier/prettier\n[npm-downloads-image]: https://img.shields.io/npm/dm/@atlas/transaction-confirmation?style=flat\n[npm-image]: https://img.shields.io/npm/v/@atlas/transaction-confirmation?style=flat\n[npm-url]: https://www.npmjs.com/package/@atlas/transaction-confirmation\n\n# @atlas/transaction-confirmation\n\nThis package contains utilities for confirming transactions and for building your own transaction confirmation strategies.\n\n## Functions\n\n### `createBlockHeightExceedencePromiseFactory()`\n\nWhen a transaction's lifetime is tied to a blockhash, that transaction can be landed on the network until that blockhash expires. All blockhashes have a block height after which they are considered to have expired. A block height exceedence promise throws when the network progresses past that block height.\n\n```ts\nimport { isAtlasError, AtlasError } from '@atlas/errors';\nimport { createBlockHeightExceedencePromiseFactory } from '@atlas/transaction-confirmation';\n\nconst getBlockHeightExceedencePromise = createBlockHeightExceedencePromiseFactory({\n    rpc,\n    rpcSubscriptions,\n});\ntry {\n    await getBlockHeightExceedencePromise({ lastValidBlockHeight });\n} catch (e) {\n    if (isAtlasError(e, ATLAS_ERROR__BLOCK_HEIGHT_EXCEEDED)) {\n        console.error(\n            `The block height of the network has exceeded ${e.context.lastValidBlockHeight}. ` +\n                `It is now ${e.context.currentBlockHeight}`,\n        );\n        // Re-sign and retry the transaction.\n        return;\n    }\n    throw e;\n}\n```\n\n### `createNonceInvalidationPromiseFactory()`\n\nWhen a transaction's lifetime is tied to the value stored in a nonce account, that transaction can be landed on the network until the nonce is advanced to a new value. A nonce invalidation promise throws when the value stored in a nonce account is not the expected one.\n\n```ts\nimport { isAtlasError, AtlasError } from '@atlas/errors';\nimport { createNonceInvalidationPromiseFactory } from '@atlas/transaction-confirmation';\n\nconst getNonceInvalidationPromise = createNonceInvalidationPromiseFactory({\n    rpc,\n    rpcSubscriptions,\n});\ntry {\n    await getNonceInvalidationPromise({\n        currentNonceValue,\n        nonceAccountAddress,\n    });\n} catch (e) {\n    if (isAtlasError(e, ATLAS_ERROR__NONCE_INVALID)) {\n        console.error(`The nonce has advanced to ${e.context.actualNonceValue}`);\n        // Re-sign and retry the transaction.\n        return;\n    } else if (isAtlasError(e, ATLAS_ERROR__NONCE_ACCOUNT_NOT_FOUND)) {\n        console.error(`No nonce account was found at ${nonceAccountAddress}`);\n    }\n    throw e;\n}\n```\n\n### `createRecentSignatureConfirmationPromiseFactory()`\n\nThe status of recently-landed transactions is available in the network's status cache. A recent signature confirmation promise resolves when a transaction achieves the target confirmation commitment, and throws when the transaction fails with an error.\n\n```ts\nimport { createRecentSignatureConfirmationPromiseFactory } from '@atlas/transaction-confirmation';\n\nconst getRecentSignatureConfirmationPromise = createRecentSignatureConfirmationPromiseFactory({\n    rpc,\n    rpcSubscriptions,\n});\ntry {\n    await getRecentSignatureConfirmationPromise({\n        commitment,\n        signature,\n    });\n    console.log(`The transaction with signature \\`${signature}\\` has achieved a commitment level of \\`${commitment}\\``);\n} catch (e) {\n    console.error(`The transaction with signature \\`${signature}\\` failed`, e.cause);\n    throw e;\n}\n```\n\n### `getTimeoutPromise()`\n\nWhen no other heuristic exists to infer that a transaction has expired, you can use this promise factory with a commitment level. It throws after 30 seconds when the commitment is `processed`, and 60 seconds otherwise. You would typically race this with another confirmation strategy.\n\n```ts\nimport { safeRace } from '@atlas/promises';\nimport { getTimeoutPromise } from '@atlas/transaction-confirmation';\n\ntry {\n    await safeRace([getCustomTransactionConfirmationPromise(/* ... */), getTimeoutPromise({ commitment })]);\n} catch (e) {\n    if (e instanceof DOMException && e.name === 'TimeoutError') {\n        console.log('Could not confirm transaction after a timeout');\n    }\n    throw e;\n}\n```\n\n### `waitForDurableNonceTransactionConfirmation()`\n\nSupply your own confirmation implementations to this function to create a custom nonce transaction confirmation strategy.\n\n```ts\nimport { waitForDurableNonceTransactionConfirmation } from '@atlas/transaction-confirmation';\n\ntry {\n    await waitForDurableNonceTransactionConfirmation({\n        getNonceInvalidationPromise({ abortSignal, commitment, currentNonceValue, nonceAccountAddress }) {\n            // Return a promise that rejects when a nonce becomes invalid.\n        },\n        getRecentSignatureConfirmationPromise({ abortSignal, commitment, signature }) {\n            // Return a promise that resolves when a transaction achieves confirmation\n        },\n    });\n} catch (e) {\n    // Handle errors.\n}\n```\n\n### `waitForRecentTransactionConfirmation()`\n\nSupply your own confirmation implementations to this function to create a custom confirmation strategy for recently-landed transactions.\n\n```ts\nimport { waitForRecentTransactionConfirmation } from '@atlas/transaction-confirmation';\n\ntry {\n    await waitForRecentTransactionConfirmation({\n        getBlockHeightExceedencePromise({ abortSignal, commitment, lastValidBlockHeight }) {\n            // Return a promise that rejects when the blockhash's block height has been exceeded\n        },\n        getRecentSignatureConfirmationPromise({ abortSignal, commitment, signature }) {\n            // Return a promise that resolves when a transaction achieves confirmation\n        },\n    });\n} catch (e) {\n    // Handle errors.\n}\n```\n\n### `waitForRecentTransactionConfirmationUntilTimeout()`\n\nSupply your own confirmation implementations to this function to create a custom nonce transaction confirmation strategy.\n\n```ts\nimport { waitForRecentTransactionConfirmationUntilTimeout } from '@atlas/transaction-confirmation';\n\ntry {\n    await waitForRecentTransactionConfirmationUntilTimeout({\n        getTimeoutPromise({ abortSignal, commitment }) {\n            // Return a promise that rejects after your chosen timeout\n        },\n        getRecentSignatureConfirmationPromise({ abortSignal, commitment, signature }) {\n            // Return a promise that resolves when a transaction achieves confirmation\n        },\n    });\n} catch (e) {\n    // Handle errors.\n}\n```\n","readmeFilename":"README.md","_rev":"1-da01898681b705013234b0a3c61a628c"}