{"_id":"@atlaschain/addresses","name":"@atlaschain/addresses","dist-tags":{"latest":"3.0.0"},"versions":{"3.0.0":{"name":"@atlaschain/addresses","version":"3.0.0","description":"Helpers for generating account addresses","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"],"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/@atlas/test-config/jest-dev.config.ts --rootDir . --watch","prepublishOnly":"pnpm pkg delete devDependencies","publish-impl":"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\" ] && ../build-scripts/maybe-tag-latest.ts $npm_package_name@$npm_package_version) || true))","publish-packages":"pnpm prepublishOnly && pnpm publish-impl","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/@atlas/test-config/jest-lint.config.ts --rootDir . --silent","test:prettier":"TERM_OVERRIDE=\"${TURBO_HASH:+dumb}\" TERM=${TERM_OVERRIDE:-$TERM} jest -c ../../node_modules/@atlas/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/@atlas/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/@atlas/test-config/jest-unit.config.node.ts --rootDir . --silent"},"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/assertions":"workspace:*","@atlaschain/codecs-core":"workspace:*","@atlaschain/codecs-strings":"workspace:*","@atlaschain/errors":"workspace:*","@atlaschain/nominal-types":"workspace:*"},"peerDependencies":{"typescript":">=5.3.3"},"engines":{"node":">=20.18.0"},"_id":"@atlaschain/addresses@3.0.0","homepage":"https://github.com/anza-xyz/kit#readme","_nodeVersion":"22.12.0","_npmVersion":"10.9.0","dist":{"integrity":"sha512-9GIIbMrKTj2KYV984FZ82CCckVfgIA19RirVcHmVhOHSmqAxhypCwab2EbvJdz5S8+N7c8jEJgx8pBpdeG9oVw==","shasum":"7352094b16f9c2ab47feb33d570a3452aa3c70f8","tarball":"https://registry.npmjs.org/@atlaschain/addresses/-/addresses-3.0.0.tgz","fileCount":5,"unpackedSize":21627,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQD4N8+b/uzGe5TBn/ltH1Us+Y7bhMrV5yH+o3T+m6kLjwIgYKfOP4rWZIoUZMlcS5WrwChzhIIT0veWh8xuALbv4H8="}]},"_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/addresses_3.0.0_1756885188430_0.7285357555987582"},"_hasShrinkwrap":false}},"time":{"created":"2025-09-03T07:39:48.314Z","3.0.0":"2025-09-03T07:39:48.625Z","modified":"2025-09-03T07:39:48.882Z"},"maintainers":[{"name":"atlaschain","email":"jq@atlaschain.org"}],"description":"Helpers for generating account addresses","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/addresses?style=flat\n[npm-image]: https://img.shields.io/npm/v/@atlas/addresses?style=flat\n[npm-url]: https://www.npmjs.com/package/@atlas/addresses\n\n# @atlas/addresses\n\nThis package contains utilities for generating account addresses. It can be used standalone, but it is also exported as part of Kit [`@atlas/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit).\n\n## Types\n\n### `Address`\n\nThis type represents a string that validates as a Atlas address. Functions that require well-formed addresses should specify their inputs in terms of this type.\n\nWhenever you need to validate an arbitrary string as a base58-encoded address, use the `address()`, `assertIsAddress()`, or `isAddress()` functions in this package.\n\n### `ProgramDerivedAddress`\n\nThis type represents the tuple of a program derived address and the bump seed used to ensure that the address, as derived, is not found on the Ed25519 curve.\n\nWhenever you need to validate an arbitrary tuple as one that represents a program derived address, use the `assertIsProgramDerivedAddress()` or `isProgramDerivedAddress()` functions in this package.\n\n### `ProgramDerivedAddressBump`\n\nThis type represents an integer between 0-255 used as a seed when deriving a program derived address. The purpose of this value is to modify the derivation enough to ensure that the derived address does not find itself on the Ed25519 curve.\n\n## Functions\n\n### `address()`\n\nThis helper combines _asserting_ that a string is an address with _coercing_ it to the `Address` type. It's best used with untrusted input.\n\n```ts\nimport { address } from '@atlas/addresses';\n\nawait transfer(address(fromAddress), address(toAddress), lamports(100000n));\n```\n\nWhen starting from a known-good address as a string, it's more efficient to typecast it rather than to use the `address()` helper, because the helper unconditionally performs validation on its input.\n\n```ts\nimport { Address } from '@atlas/addresses';\n\nconst MEMO_PROGRAM_ADDRESS =\n    'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr' as Address<'MemoSq4gqABAXKb96qnH8TysNcWxMyWCqXgDLGmfcHr'>;\n```\n\n### `assertIsAddress()`\n\nClient applications primarily deal with addresses and public keys in the form of base58-encoded strings. Addresses returned from the RPC API conform to the type `Address`. You can use a value of that type wherever a base58-encoded address is expected.\n\nFrom time to time you might acquire a string, that you expect to validate as an address, from an untrusted network API or user input. To assert that such an arbitrary string is a base58-encoded address, use the `assertIsAddress` function.\n\n```ts\nimport { assertIsAddress } from '@atlas/addresses';\n\n// Imagine a function that fetches an account's balance when a user submits a form.\nfunction handleSubmit() {\n    // We know only that what the user typed conforms to the `string` type.\n    const address: string = accountAddressInput.value;\n    try {\n        // If this type assertion function doesn't throw, then\n        // Typescript will upcast `address` to `Address`.\n        assertIsAddress(address);\n        // At this point, `address` is an `Address` that can be used with the RPC.\n        const balanceInLamports = await rpc.getBalance(address).send();\n    } catch (e) {\n        // `address` turned out not to be a base58-encoded address\n    }\n}\n```\n\n### `assertIsProgramDerivedAddress()`\n\nIn the event that you receive an address/bump-seed tuple from some untrusted source, you can assert that such a tuple conforms to the `ProgramDerivedAddress` type using this function.\n\nSee [`assertIsAddress()`](#assertisaddress) for an example of how to use an assertion function.\n\n### `createAddressWithSeed()`\n\nReturns a base58-encoded address derived from some base address, some program address, and a seed string or byte array.\n\n```ts\nimport { createAddressWithSeed } from '@atlas/addresses';\n\nconst derivedAddress = await createAddressWithSeed({\n    // The private key associated with this address will be able to sign for `derivedAddress`.\n    baseAddress: 'B9Lf9z5BfNPT4d5KMeaBFx8x1G4CULZYR1jA2kmxRDka' as Address,\n    // Only this program will be able to write data to this account.\n    programAddress: '445erYq578p2aERrGW9mn9KiYe3fuG6uHdcJ2LPPShGw' as Address,\n    seed: 'data-account',\n});\n```\n\n### `getAddressDecoder()`\n\nReturns a decoder that you can use to convert an array of 32 bytes representing an address to the base58-encoded representation of that address. Returns a tuple of the `Address` and the offset within the byte array at which the decoder stopped reading.\n\n```ts\nimport { getAddressDecoder } from '@atlas/addresses';\n\nconst addressBytes = new Uint8Array([\n    150, 183, 190, 48, 171, 8, 39, 156, 122, 213, 172, 108, 193, 95, 26, 158, 149, 243, 115, 254, 20, 200, 36, 30, 248,\n    179, 178, 232, 220, 89, 53, 127,\n]);\nconst addressDecoder = getAddressDecoder();\nconst address = addressDecoder.decode(address); // B9Lf9z5BfNPT4d5KMeaBFx8x1G4CULZYR1jA2kmxRDka\n```\n\n### `getAddressEncoder()`\n\nReturns an encoder that you can use to encode a base58-encoded address to a byte array.\n\n```ts\nimport { getAddressEncoder } from '@atlas/addresses';\n\nconst address = 'B9Lf9z5BfNPT4d5KMeaBFx8x1G4CULZYR1jA2kmxRDka' as Address;\nconst addressEncoder = getAddressEncoder();\nconst addressBytes = addressEncoder.encode(address);\n// Uint8Array(32) [\n//   150, 183, 190,  48, 171,   8, 39, 156,\n//   122, 213, 172, 108, 193,  95, 26, 158,\n//   149, 243, 115, 254,  20, 200, 36,  30,\n//   248, 179, 178, 232, 220,  89, 53, 127\n// ]\n```\n\n### `getAddressFromPublicKey()`\n\nGiven a public `CryptoKey`, this method will return its associated `Address`.\n\n```ts\nimport { getAddressFromPublicKey } from '@atlas/addresses';\n\nconst address = await getAddressFromPublicKey(publicKey);\n```\n\n### `getProgramDerivedAddress()`\n\nGiven a program's `Address` and up to 16 `Seeds`, this method will return the program derived address (PDA) associated with each.\n\n```ts\nimport { getAddressEncoder, getProgramDerivedAddress } from '@atlas/addresses';\n\nconst addressEncoder = getAddressEncoder();\nconst [pda, bumpSeed] = await getProgramDerivedAddress({\n    programAddress: 'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL' as Address,\n    seeds: [\n        // Owner\n        addressEncoder.encode('9fYLFVoVqwH37C3dyPi6cpeobfbQ2jtLpN5HgAYDDdkm' as Address),\n        // Token program\n        addressEncoder.encode('TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' as Address),\n        // Mint\n        addressEncoder.encode('EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v' as Address),\n    ],\n});\n```\n\n### `isAddress()`\n\nThis is a type guard that accepts a string as input. It will both return `true` if the string conforms to the `Address` type and will refine the type for use in your program.\n\n```ts\nimport { isAddress } from '@atlas/addresses';\n\nif (isAddress(ownerAddress)) {\n    // At this point, `ownerAddress` has been refined to a\n    // `Address` that can be used with the RPC.\n    const { value: lamports } = await rpc.getBalance(ownerAddress).send();\n    setBalanceLamports(lamports);\n} else {\n    setError(`${ownerAddress} is not an address`);\n}\n```\n\n### `isProgramDerivedAddress()`\n\nThis is a type guard that accepts a tuple as input. It will both return `true` if the tuple conforms to the `ProgramDerivedAddress` type and will refine the type for use in your program.\n\nSee [`isAddress()`](#isaddress) for an example of how to use a type guard.\n","readmeFilename":"README.md","_rev":"1-bd7f59fab59a57f394032bec3987d0ca"}