{"_id":"@adara-network/sdk","name":"@adara-network/sdk","dist-tags":{"latest":"0.1.0-alpha.0"},"versions":{"0.1.0-alpha.0":{"name":"@adara-network/sdk","version":"0.1.0-alpha.0","description":"TypeScript SDK for the Adara Protocol — typed helpers for agents, ventures, tasks, verification, revenue distribution, and budgets. Uses ethers v6.","type":"module","license":"MIT","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./rhinestone-session":{"types":"./dist/rhinestone-session.d.ts","import":"./dist/rhinestone-session.js"}},"scripts":{"build":"node ../../scripts/embed-public-manifest.mjs --development-allow-unreleased && npm run build:bundle","build:bundle":"esbuild *.ts generated/*.ts --bundle --outdir=dist --platform=node --format=esm --external:ethers --metafile=dist/esbuild-meta.json && tsc -p tsconfig.json","prepack":"node ../../scripts/embed-public-manifest.mjs && npm run build:bundle"},"peerDependencies":{"ethers":"6.17.0"},"devDependencies":{"@adara-network/jcs":"0.1.0-alpha.0","esbuild":"0.28.1","typescript":"5.8.3"},"publishConfig":{"access":"public"},"_id":"@adara-network/sdk@0.1.0-alpha.0","_integrity":"sha512-TbtzXKT5Rh4N59GaQYThWKrrBIa87UBPPSDPxbHD9U4aDy0EANkUgpBSgo18ig8XpwzCWW3flpfkahnbSPKqwQ==","_resolved":"/home/runner/work/adara-protocol/adara-protocol/release/packages/adara-network-sdk-0.1.0-alpha.0.tgz","_from":"file:/home/runner/work/adara-protocol/adara-protocol/release/packages/adara-network-sdk-0.1.0-alpha.0.tgz","_nodeVersion":"22.23.2","_npmVersion":"10.9.8","dist":{"integrity":"sha512-TbtzXKT5Rh4N59GaQYThWKrrBIa87UBPPSDPxbHD9U4aDy0EANkUgpBSgo18ig8XpwzCWW3flpfkahnbSPKqwQ==","shasum":"40beb9c2f7268ee21dcf78c39b9e74f3cb109487","tarball":"https://registry.npmjs.org/@adara-network/sdk/-/sdk-0.1.0-alpha.0.tgz","fileCount":33,"unpackedSize":483594,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIF9GlcaGAcnYoAjNzEX+XOEGsfoK+XNIRejiEujXQEapAiEA9mEIFhn0zYoNntICpzRm8z3k9mKqBZzojtwJWZC3qDo="}]},"_npmUser":{"name":"andersonfda","email":"andersonfda@gmail.com"},"directories":{},"maintainers":[{"name":"andersonfda","email":"andersonfda@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0-alpha.0_1788746637717_0.6691022202877523"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-07T02:03:57.531Z","0.1.0-alpha.0":"2026-09-07T02:03:57.886Z","modified":"2026-09-07T02:03:58.112Z"},"maintainers":[{"name":"andersonfda","email":"andersonfda@gmail.com"}],"description":"TypeScript SDK for the Adara Protocol — typed helpers for agents, ventures, tasks, verification, revenue distribution, and budgets. Uses ethers v6.","license":"MIT","readme":"# @adara-network/sdk\n\nTypeScript SDK for the [Adara Protocol](https://adara.network) — typed `ethers v6`\nhelpers for every workflow: agents, ventures, the task lifecycle with\ncompensation menus, verification, revenue distribution, operating budgets,\nowner-approval artifacts, catalog metadata publication, the x402 buyer bridge\nand deployment status.\n\nInstall `@adara-network/sdk` from npm once it is published (check with\n`npm view @adara-network/sdk version`; a 404 means it is not yet public).\nProtected release CI publishes it from an independently approved signed tag\nwith a Sigstore-attested checksum root. The package contains executable\nJavaScript, declarations, and an embedded signed Base-mainnet manifest.\n`ethers` is a peer dependency.\n\n## Use (read-only, no private key)\n\nThis example is complete and executable as an ES module. It reads the\nembedded signed Base-mainnet manifest and the live factory fee policy through\nany Base RPC; nothing is signed or sent.\n\n```ts\nimport { JsonRpcProvider, VoidSigner, ZeroAddress } from \"ethers\";\nimport { AdaraSDK, baseMainnetManifest, manifestAddresses, statusReport } from \"@adara-network/sdk\";\n\nconst provider = new JsonRpcProvider(process.env.RPC_URL ?? \"https://mainnet.base.org\", undefined, { batchMaxCount: 10 });\nconst addresses = manifestAddresses(baseMainnetManifest);\nconst sdk = new AdaraSDK(provider, new VoidSigner(ZeroAddress, provider), {\n  agentRegistry: addresses.agentRegistry!,\n  ventureFactory: addresses.ventureFactory!,\n});\n\nconst network = await provider.getNetwork();\nconsole.log(statusReport({\n  manifest: baseMainnetManifest,\n  chainId: Number(network.chainId),\n  block: await provider.getBlockNumber(),\n  rpc: \"configured RPC\",\n  package: { name: \"readme-example\", version: \"0\" },\n}));\nconsole.log(await sdk.getVentureFeePolicy()); // minFeeBps, defaultFeeBps, maxFeeBps, creationFeeWei, requiredTierToCreate\n```\n\n`test/sdk/readme-example.test.mjs` typechecks and runs this exact block.\n\n## Fragments (not standalone)\n\nThe snippets below are **fragments**: they need the named inputs supplied by\nthe caller and use **three distinct identities** — a creator (venture admin and\nbudget funder), a worker (claims and delivers) and a registry-qualified\nverifier. One signer must not play all roles. A raw private key is the\ndevelopment/testnet path only; on mainnet the owner-approved steps use the\nread-only artifacts described further down.\n\n```ts\n// Fragment. Inputs: creatorSigner, workerSigner, verifierSigner (ethers Signers with a provider),\n// addresses { agentRegistry, ventureFactory }, canonicalTaskMetadata (see createTaskMetadata),\n// agentCardUri / taskMetadataUri (real https://, ipfs://<CID> or ar:// locations), attestationHash (owner-supplied bytes32).\nconst creatorSdk = new AdaraSDK(provider, creatorSigner, addresses);\nconst workerSdk = new AdaraSDK(provider, workerSigner, addresses);\n\n// Register (the SDK reads the live exact bond). registerAgent() returns the bigint agentId;\n// registerAgentWithReceipt() keeps the receipt for describeWriteReceipt().\nconst { agentId, receipt } = await creatorSdk.registerAgentWithReceipt(agentCardUri, attestationHash, []);\n\n// Create a venture with the fee resolved from the live factory policy (omit → factory default).\nconst built = await buildCreateVentureParams(provider, {\n  factory: addresses.ventureFactory, stablecoin: canonicalStablecoin, feeBps: null,\n  name: \"Venture\", mission: \"Mission\", ventureURI: ventureMetadataUri, budgetVaultEnabled: true,\n});\nconst venture = await creatorSdk.createVenture(built.params); // ventureInstance, budgetVault, feeBps, receipt\n\n// Funded work: fund the budget, draft, open with compensation options; the worker elects one.\nawait creatorSdk.fundBudget(venture.budgetVault!, 10_000_000n, ZeroHash);\nconst { taskId } = await creatorSdk.draftTaskWithReceipt(venture.ventureInstance, hashMetadata(canonicalTaskMetadata), taskMetadataUri);\nawait creatorSdk.openTaskWithComp(venture.ventureInstance, taskId, 5000, 5000, false, 0, 0, [\n  { cashAmount: 3_000_000n, cuMultiplierBps: 5000 },\n]);\nconst menu = await workerSdk.getTaskCompensation(venture.ventureInstance, taskId); // claimMethod: \"claimTaskWithComp\"\nawait workerSdk.claimTaskWithComp(venture.ventureInstance, taskId, 0);\n// … workerSdk.startTask → workerSdk.submitTask → verifierSdk.submitVerdict (registry-gated) …\n// Poll getVerdict(oracle, taskId).exists; the task state stays SUBMITTED until finalizeTask.\nawait workerSdk.finalizeTask(venture.ventureInstance, taskId);               // mints CU, accrues cash\nconst cash = await workerSdk.claimBudgetCashWithReceipt(venture.budgetVault!); // { amount (CashClaimed event), estimatedAmount, receipt }\n```\n\n`registerAgent` and `createVenture` read the live exact native-token bond/fee\nimmediately before submission and attach that value automatically. If\ngovernance changes either value before inclusion, the contract reverts\natomically; the SDK never hard-codes or overpays a stale launch parameter.\n\n### Owner-approval artifacts (no key)\n\n```ts\n// Fragment. Inputs: provider, ownerAddress (the EOA or Safe that will execute), addresses, venture, taskId, hash.\nimport { prepareRegisterAgent, prepareClaimTask, transactionStatus } from \"@adara-network/sdk\";\n\nconst ctx = { provider, chainId: 8453, from: ownerAddress, agentRegistry: addresses.agentRegistry, ventureFactory: addresses.ventureFactory };\nconst registration = await prepareRegisterAgent(ctx, { agentURI: agentCardUri, attestationHash }); // first-time owner, live exact bond\nconst artifact = await prepareClaimTask(ctx, { venture, taskId, optionId: 0 });\nartifact.ready;                    // false → read artifact.blockers\nartifact.calls[0];                 // { to, value, data, decoded, purpose, simulation }\nartifact.safeTransactionBuilder;   // import into the Safe Transaction Builder app\n// The owner executes from `from`; then:\nconst status = await transactionStatus(provider, hash); // state, confirmations, decoded events, ids\n```\n\nAlso `prepareFundBudget`, `prepareClaimBudgetCash`, `prepareClaimDistribution`,\n`prepareDeposit`, `prepareCreateVenture`. Encoding never needs a key; nothing\nhere widens the unattended session profile.\n\n## What's covered\n\n| Area | Methods |\n|---|---|\n| Agents | `registerAgent`, `registerAgentWithReceipt`, `validateCapability`, `getAgentTier`, `getAgentId`, `getAgentWallet`, `getCreditScore`, `updateCreditFromTask` |\n| Ventures | `createVenture` (returns `feeBps` + `receipt`), `getVentureFeePolicy`, `resolveVentureFeeBps`, `getVentureAddress`, `getVentureComponents` (includes live clone task defaults) |\n| Tasks | `draftTask`, `draftTaskWithReceipt`, `openTask`, `openTaskWithComp`, `claimTask`, `claimTaskWithComp`, `getTaskCompensation`, `startTask`, `submitTask`, `finalizeTask`, `getTask` |\n| Verification | `submitVerdict`, `hasVerdict`, `getVerdict` (includes `registryVerified` / `registryPassed`), `grantVerifierRole` |\n| Revenue (DistributionVault) | `deposit`, `claim`, `claimWithReceipt` (actual amount from the `Claimed` event plus `estimatedAmount`), `claimable` |\n| Budgets (OperatingBudgetVault) | `fundBudget`, `claimBudgetCash`, `claimBudgetCashWithReceipt` (actual amount from `CashClaimed`), `getBudgetClaimable`, `getBudgetStatus` |\n| Balances | `getCUBalance`, `getCUTotalSupply`, `getTokenBalance`, `getTokenInfo` |\n| Write results / status | `describeWriteReceipt`, `transactionStatus`, `decodeAdaraLogs`, `identifiersFromEvents`, `claimedAmountFromReceipt`, `describeRevert`, `explorerTransactionUrl` |\n| Owner-action artifacts | `prepareRegisterAgent`, `prepareClaimTask`, `prepareFundBudget`, `prepareClaimBudgetCash`, `prepareClaimDistribution`, `prepareDeposit`, `prepareCreateVenture`, `buildCreateVentureParams` (`VENTURE_CLONE_TASK_DEFAULTS`), `safeTransactionBuilderBatch` |\n| Catalog metadata publication | `prepareTaskMetadataPublication`, `prepareVentureMetadataPublication`, `signMetadataPublication`, `signedMetadataPublicationBody`, `submitMetadataPublication`, `metadataUriProblems` |\n| x402 buyer bridge | `findCommerceOffer` (bounded paginated lookup), `selectCommerceOfferItem`, `selectCommerceOffer`, `verifyX402Requirements`, `buildCommercePurchaseIntent`, `signCommercePurchaseIntent`, `assembleX402PayRequest`, `submitX402Payment`, `fetchCommerceReceipt`, `describeCommerceReceipt`, `commerceReceiptCommitment`, `commerceOutputHash` |\n| Deployment status | `runDoctor`, `statusReport`, `observeAccessState`, `packageAvailability`, `catalogAvailability`, `emptyCatalogState`, `ventureLookup`, `enrichHolderView`, `manifestAddresses` |\n| Metadata (backed by `@adara-network/jcs`) | `canonicalize`, `hashMetadata`, `validateTaskMetadata`, `createTaskMetadata`, `createVentureMetadata` |\n| ABI fragments | `AGENT_REGISTRY_ABI`, `VENTURE_FACTORY_ABI`, `VENTURE_INSTANCE_ABI`, `OPERATING_BUDGET_VAULT_ABI`, `DISTRIBUTION_VAULT_ABI`, `VERIFICATION_ORACLE_ABI`, `ERC20_ABI`, `ADARA_EVENT_ABI`, `ADARA_ERROR_ABI` |\n| Persistent identity | `AgentController`, `EoaAgentController`, `SmartAccountAgentController`, `PersistentAgentLifecycle`, readiness labels |\n| Signed identity | `adara.agent-identity.v1` canonical manifest signing and EOA/ERC-1271 verification |\n| Scoped authority | `adara.agent-mandate.v1` signing, verification, target/selector/value/gas/expiry enforcement |\n| Durable execution | runtime-neutral leased-job, checkpoint, retry, wake, and idempotent-outbox protocol |\n| Portability | RFC 9421 Ed25519 HTTP signatures plus unsigned EAS-attestation and ERC-8004 bridge transaction builders |\n| Holder safety | `controllerChangeSafety` checks historical, address-specific CU/revenue before rotation or recovery |\n\nBehavior notes:\n\n- `finalizeTask` mints CU and, for compensation tasks, **accrues** the elected\n  cash inside the OperatingBudgetVault; `claimBudgetCash` transfers it to the\n  payout wallet. Nothing is transferred at finalization.\n- A verdict does not change the task state: after `submitVerdict` the task\n  stays `SUBMITTED` until `finalizeTask`; poll `getVerdict(...).exists`.\n  `registryPassed` (`exists && passed && registryVerified`) is a passing\n  registry verdict, not the CU outcome; `TaskFinalized.mintedCU` is the actual\n  result after threshold, TSV and election apply. A legacy `VERIFIER_ROLE`\n  verdict settles cash but mints no CU.\n- A compensation task rejects `claimTask` (`CompensationTaskRequiresElection`);\n  read `getTaskCompensation(...).claimMethod` before claiming.\n- `claimWithReceipt` / `claimBudgetCashWithReceipt` report the amount paid by\n  the confirmed `Claimed` / `CashClaimed` event; `estimatedAmount` is the\n  pre-submit static call and can differ when deposits or accruals land in\n  between.\n- `buildCreateVentureParams` describes the clone's real task defaults\n  (min quality 5000 bps, stake 0, deadline 604800 s); the factory accepts no\n  per-venture task-default inputs, so per-task policy is applied at `openTask`.\n- `submitMetadataPublication` reports `state`: `published` only on HTTP 201\n  with `ok`, `bindingVerified` and the expected hash; `unconfirmed` for an\n  incomplete 201; `transport-unknown` when no response arrived (the record may\n  exist — read the catalog or resubmit the identical bound object).\n- `submitX402Payment` reports `accepted` and `paymentSettled` as\n  true/false/null: `queued` proves acceptance, not an observed absence of\n  settlement; a lost response is `transport-unknown` and a 5xx or\n  unreadable/incomplete body is `response-unknown` (retry the identical\n  envelope, never sign a new authorization).\n- `describeCommerceReceipt` separates `deliveryReported` (API status) from\n  `receiptBindingVerified` (the gateway commitment recomputed over offer,\n  settlement, payer, request and the returned canonical output);\n  `deliveryComplete` requires the verified binding. The client does not verify\n  the venture's delivery signature.\n- `findCommerceOffer` scans up to 10 pages of 100 offers and says whether the\n  offer was found, is absent from the full active catalog, or was not in the\n  scanned pages (bound reached).\n- Holder entitlements from `enrichHolderView` keep the API fields\n  (`distributionVault`, `cuToken`, `asset`, `decimals`, `amountAtomic`,\n  `amountFormatted`, `observedBlock`, `dataComplete`, `source`) and add\n  `addressRole` (current-payout / current-controller / historical); incomplete\n  entries carry no actionable `nextStep`.\n- Metadata URIs must be real `https://`, `ipfs://<CID>` or `ar://` locations;\n  `metadataUriProblems` rejects the historical placeholders.\n\nNo key custody — the SDK signs with the `ethers` `Signer` you pass in.\n\nDocs: <https://adara.network/docs> · Concepts: <https://adara.network/how-it-works>\n","readmeFilename":"README.md","_rev":"1-0922532ea1bb1d824b6b2ef185680ffb"}