{"id":18556769,"url":"https://github.com/urbit/azimuth-js","last_synced_at":"2025-04-10T01:31:34.930Z","repository":{"id":37549375,"uuid":"139600375","full_name":"urbit/azimuth-js","owner":"urbit","description":"JavaScript bindings for Azimuth (https://github.com/urbit/azimuth)","archived":false,"fork":false,"pushed_at":"2023-03-03T11:30:44.000Z","size":5858,"stargazers_count":19,"open_issues_count":10,"forks_count":12,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-03-18T15:45:57.886Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/urbit.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-07-03T15:04:24.000Z","updated_at":"2024-09-24T10:20:18.000Z","dependencies_parsed_at":"2024-06-20T00:10:01.211Z","dependency_job_id":"f0050294-39f7-4033-b85b-fd6ebd808849","html_url":"https://github.com/urbit/azimuth-js","commit_stats":{"total_commits":266,"total_committers":17,"mean_commits":"15.647058823529411","dds":0.5338345864661654,"last_synced_commit":"aa52d2a70e53661ce02d0d9fefac7cf7b3d193f2"},"previous_names":["urbit/constitution-js"],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Fazimuth-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Fazimuth-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Fazimuth-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/urbit%2Fazimuth-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/urbit","download_url":"https://codeload.github.com/urbit/azimuth-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247828812,"owners_count":21002975,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-06T21:33:13.674Z","updated_at":"2025-04-10T01:31:29.915Z","avatar_url":"https://github.com/urbit.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# azimuth-js\n\n[![Build Status](https://secure.travis-ci.org/urbit/azimuth-js.png)](http://travis-ci.org/urbit/azimuth-js)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/urbit/azimuth-js/blob/master/LICENSE)\n[![npm](https://img.shields.io/npm/v/azimuth-js.svg)](https://www.npmjs.com/package/azimuth-js)\n\nInteract with [Azimuth](https://github.com/urbit/azimuth) from\nJavascript.\n\n## Install\n\nJust grab from npm like so:\n\n```\nnpm install azimuth-js\n```\n\n## API Reference\n\n[./docs/](./docs/api.md)\n\n## Quickstart\n\n(This example uses an [Infura](https://infura.io/) endpoint as a provider for\nweb3.)\n\n```\nconst ajs = require('azimuth-js')\nconst Web3 = require('web3')\n\nconst infura   = `https://mainnet.infura.io/v3/${MY_INFURA_ID}`\nconst provider = new Web3.providers.HttpProvider(infura)\nconst web3     = new Web3(provider)\n\nconst contracts = await ajs.initContractsPartial(web3, ajs.azimuth.mainnet)\n\nconst zod = '0x9F57C77b1095BD5Db0558b9Cb9b8e6Fc67375E3C'\n\najs.azimuth.isOwner(contracts, 0, zod).then(console.log) // true\n```\n\n## Usage\n\nRequire the library via something like:\n\n```javascript\nconst azimuthjs = require('azimuth-js');\n```\n\nIn general: use the functions in `azimuthjs.ecliptic`, `azimuthjs.azimuth`,\n`azimuthjs.polls`, and so on to interact with the corresponding Ethereum\ncontract.  Use `azimuthjs.check` to verify any required state is what you expect\nit to be.  `azimuthjs.txn` contains functions for signing and sending\ntransactions, and `azimuthjs.utils` mostly re-exports useful utility functions\nfrom [ethereumjs-util](https://github.com/ethereumjs/ethereumjs-util).\n\nYou might want to define something like the following, for convenience:\n\n```javascript\nconst ecliptic = azimuthjs.ecliptic;\nconst azimuth = azimuthjs.azimuth;\nconst check = azimuthjs.check;\nconst txn = azimuthjs.txn\n```\n\nThe library exposes a purely-functional API.  This means you'll have to supply\nyour own state (e.g. web3 instance, contracts instance) whenever dealing with\ntransactions and contract initialisation.  For example, when running a fresh\nlocal Ganache node with the appropriate mnemonic (see below), this will get you\nset up:\n\n```javascript\nconst Web3 = require('web3');\n\nlet provider = new Web3.providers.HttpProvider('http://localhost:8545');\nlet web3 = new Web3(provider);\n\nlet contractAddresses = {\n    ecliptic: '0x56db68f29203ff44a803faa2404a44ecbb7a7480',\n    azimuth:  '0x863d9c2e5c4c133596cfac29d55255f0d0f86381',\n    polls:    '0x935452c45eda2958976a429c9733c40302995efd',\n    claims:   '0xe0834579269eac6beca2882a6a21f6fb0b1d7196'\n  }\n\nlet contracts = azimuthjs.initContracts(web3, contractAddresses);\n```\n\nNote that the web3 object is passed to `azimuthjs.initContracts` explicitly.\nAside from contract initialisation, this is typically only required when\nsending transactions (more below).\n\nWhen interacting with the contract APIs, on the other hand, you'll almost\nalways have to pass a contracts object explicitly.  For example:\n\n```javascript\n// ecliptic owner\nconst owner = '0x6deffb0cafdb11d175f123f6891aa64f01c24f7d';\n\nconst galaxy = 42;\n\ncheck.canCreateGalaxy(contracts, galaxy, owner);\n```\n\nNote that the 'contracts' object initialised previously is passed as the first\nargument.  Again, this is almost always the case.\n\nMost of the exposed contracts API consists of functions that, at most, read\nfrom the Ethereum chain state, returning some result in a Promise.  The primary\nexceptions are some of the functions in the 'ecliptic' contract; for those\nthat modify chain state, the function will return a transaction object, e.g.:\n\n```javascript\nlet tx = ecliptic.createGalaxy(contracts, galaxy, owner);\n```\n\nTo modify contract state, you'll have to sign ('signTransaction') and send\n('sendSignedTransaction') the transaction explicitly.  For example:\n\n```javascript\ntxn.signTransaction(web3, tx, pk).then(stx =\u003e\n  txn.sendSignedTransaction(web3, stx));\n```\n\nor, in the body of an `async` function, you can use `await`:\n\n```javascript\nlet stx = await txn.signTransaction(web3, tx, pk);\ntxn.sendSignedTransaction(web3, stx);\n```\n\nNote again that, when dealing with transactions, a web3 object must be passed\nas the first argument.\n\nMany of the functions for the 'azimuth' contract will work when the function is\npassed either a point identifier (i.e. an unsigned integer), meaning the\ncomputation will be carried out on-chain, or a point object (i.e. something that\nhas been retrieved via 'azimuth.getPoint'), meaning the computation will be\ncarried out purely, simply by reference to the point object.  The result is\nwrapped in a Promise, in either case.\n\nFunctions that use Web3 may throw. The thrown object will always contain at\nleast 'name' and 'message' properties. Tread carefully when using Web3 while\noffline.\n\nContract action checks ('canXYZ') return result objects in the form of `{\nresult: bool, reason: string }`, where 'reason' is only set when 'result' is\n'false'.  These can't resolve when offline.\n\n## Development\n\n### Library Structure\n\nThe modules found in the `internal` directory are intended to be fairly close\nmappings to the public, external, or view functions located in the contracts\nthemselves.  Mostly these are re-exported via the user-facing API, defined in\n`ecliptic.js` and friends.\n\nThe one notable exception is in the `azimuth` module, where the behaviour of a\nfunction can often depend on the type of the argument passed to it.  If one\npasses them a cached `point` object (retrieved via `getPoint`), then these\nfunctions will compute their values locally; if one supplies them with a point\nnumber (i.e., an integer), they will instead hit the network.\n\n## Testing\n\nUse a simple:\n\n`npm test`\n\nto run the tests on a one-off local Ganache node.\n\n### Local Testnet\n\nFor debugging and custom testing, you'll need a local testnet running Azimuth.\n\n1. Clone [Azimuth](https://github.com/urbit/azimuth)\n2. `cd` into the repo and `npm install`\n3. `npm install -g ganache-cli`\n3. Run a local `ganache` node, boot using the following command to ensure a matching seed:\n   `ganache-cli -m \"benefit crew supreme gesture quantum web media hazard theory mercy wing kitten\"`\n4. Run `truffle deploy` from the Azimuth directory to deploy to your local node.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbit%2Fazimuth-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Furbit%2Fazimuth-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Furbit%2Fazimuth-js/lists"}