@bulla/registry 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Arkitoken, LLC
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,79 @@
1
- # Temporary Holding Version
1
+ # bulla-registry
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Auto-generated registry of Bulla protocol contract addresses, subgraph endpoints, factoring pools, and AI agent skills across all supported networks.
4
+
5
+ ## For contract addresses
6
+
7
+ Use `registry.json` — it contains all contract addresses, subgraph endpoints, factoring pools and their clients, consolidated from source repos. Do not hardcode addresses or subgraph URLs elsewhere.
8
+
9
+ `registry.schema.json` is its shape, and the contract with every consumer. Each network has one subgraph endpoint per Goldsky tag (`networks[chainId].subgraph.dev` and `.prod`). These are constant and change only when a network is added. Use `dev` in development and `prod` in production. There is no single `graphql` endpoint: the old `v2-main`/`latest` tags serve an outdated build.
10
+
11
+ ## npm package
12
+
13
+ `@bulla/registry` ships `registry.json`, `registry.schema.json`, the ABIs and the client logos, with TypeScript types generated from the schema. It is MIT-licensed (`LICENSE`), except the client logos: they belong to their owners, are included only to identify their pools, and are not covered by the license.
14
+
15
+ ```bash
16
+ npm install @bulla/registry
17
+ ```
18
+
19
+ ```ts
20
+ import { registry, type Pool, type Address } from "@bulla/registry"; // or require("@bulla/registry")
21
+
22
+ const invoice: Address | undefined = registry.networks["1"]?.contracts["bulla-contracts-v2"]?.bullaInvoice;
23
+ const active: Pool[] = registry.pools.filter((p) => p.chainId === 42161 && p.category === "active");
24
+ ```
25
+
26
+ Addresses are typed `` `0x${string}` ``, viem's `Address`.
27
+
28
+ The JSON files are importable too: `@bulla/registry/registry.json`, `@bulla/registry/registry.schema.json`, and each ABI as `@bulla/registry/abis/<repo>/<Name>.json`, e.g. `@bulla/registry/abis/bulla-contracts-v2/BullaInvoice.json`. An ABI file is the bare `abi` array: the bytecode and metadata in this repo's V1 and V2 artifacts are compiled BUSL-1.1 code and are not published.
29
+
30
+ A client's `logo` is an https URL or a path from the package root: `factoring-contracts/logos/tcs.png` is `@bulla/registry/factoring-contracts/logos/tcs.png`. A bundler needs every logo in the bundle to resolve a path at runtime, e.g. a glob import of `@bulla/registry/factoring-contracts/logos/*`.
31
+
32
+ ### Versions
33
+
34
+ The Consolidate Registry workflow releases a new version when what the package ships changed since the last release (the highest `v*` tag). A run that changes nothing publishes nothing. `scripts/release-version.ts` picks the bump:
35
+
36
+ | Change | Bump |
37
+ |--------|------|
38
+ | A removed or renamed field, a field that is no longer required, or a removed enum value (`registry.schema.json`) | **major** |
39
+ | A removed network, contract, pool, client, ABI, ABI function/event/error, or logo | **major** |
40
+ | A new field or enum value, or a new network, contract, pool, client, ABI, ABI function/event/error, or logo | **minor** |
41
+ | A changed address, endpoint or other value; any other change (e.g. a description, an ABI parameter name, a redrawn logo) | **patch** |
42
+
43
+ A rename is a removal plus an addition, so it is major. `generatedAt` is ignored, and so are ABI bytecode and metadata, which the package does not ship.
44
+
45
+ The workflow sets the version in `package.json`, commits it as bulla-registry-sync, publishes with npm trusted publishing (OIDC, no token), then tags the release (`v1.2.3`) with a GitHub release listing the changes. A change merged by hand (e.g. a schema change) is released by the next run, daily at the latest. To force a bigger bump, set a higher version in `package.json` in the PR. npm can take a few minutes after a publish to list the new version.
46
+
47
+ ## For AI agents
48
+
49
+ See `CLAUDE.md` — it serves as the entry point for agent discovery. Skill files in `<repo>/skills/*.md` describe how to perform on-chain actions step by step.
50
+
51
+ ## How it works
52
+
53
+ Each source repo (`bulla-contracts-V2`, `bulla-network-subgraph`, `factoring-contracts`) maintains a `bulla_registry_export/` folder with its addresses, ABIs, and skills. A GitHub Actions workflow, started by each source repo after a merge to main and daily as a fallback, pulls these exports and runs a consolidation script that:
54
+
55
+ 1. Merges all `address_config.json` files and factoring-contracts' `pools.json` into a single `registry.json`
56
+ 2. Checks it against `registry.schema.json`, plus the rules a schema can't express (`scripts/validate-registry.ts`). If the check fails, the run fails and nothing is written or committed
57
+ 3. Generates `CLAUDE.md` from the template based on what's in the repo
58
+
59
+ The `validate registry` PR check runs the same consolidation, so a PR that breaks the shape fails too.
60
+
61
+ A chain ID a source exports must be listed in `NETWORKS` in `scripts/consolidate.ts`, with its name and slug (its name in the subgraph, `bulla-contracts-<slug>`, and in `pools.json`); otherwise consolidation fails.
62
+
63
+ ### Changing the shape
64
+
65
+ Edit `registry.schema.json` and `scripts/consolidate.ts` together. The pool and client definitions copy factoring-contracts' `pools.schema.json` on purpose: a change there fails consolidation here until this schema is updated to match, so every change to the published shape is reviewed in this repo.
66
+
67
+ `bulla-contracts` (V1) is archived, so it is no longer pulled: its last export is committed in `bulla-contracts/` and still included in `registry.json`.
68
+
69
+ To regenerate locally:
70
+
71
+ ```bash
72
+ npm install
73
+ npm run pull:local # Copy from sibling workspace directories
74
+ npm run consolidate # Generate registry.json + CLAUDE.md, checked against registry.schema.json
75
+ npm run validate # Check the committed registry.json against the schema
76
+ npm test # Tests for the checks, the version rules and the packed package
77
+ npm run build # Build dist/ (the package's JS and types); npm pack runs it
78
+ npm run release:version # Pick the next version from the changes since the last release tag
79
+ ```
@@ -0,0 +1,206 @@
1
+ [
2
+ {
3
+ "inputs": [
4
+ {
5
+ "internalType": "address",
6
+ "name": "_bullaClaimERC721",
7
+ "type": "address"
8
+ }
9
+ ],
10
+ "stateMutability": "nonpayable",
11
+ "type": "constructor"
12
+ },
13
+ {
14
+ "inputs": [
15
+ {
16
+ "internalType": "address",
17
+ "name": "sender",
18
+ "type": "address"
19
+ }
20
+ ],
21
+ "name": "NotCreditorOrDebtor",
22
+ "type": "error"
23
+ },
24
+ {
25
+ "anonymous": false,
26
+ "inputs": [
27
+ {
28
+ "indexed": true,
29
+ "internalType": "address",
30
+ "name": "bullaManager",
31
+ "type": "address"
32
+ },
33
+ {
34
+ "indexed": true,
35
+ "internalType": "address",
36
+ "name": "bullaClaimERC721",
37
+ "type": "address"
38
+ },
39
+ {
40
+ "indexed": false,
41
+ "internalType": "address",
42
+ "name": "bullaBanker",
43
+ "type": "address"
44
+ },
45
+ {
46
+ "indexed": false,
47
+ "internalType": "uint256",
48
+ "name": "blocktime",
49
+ "type": "uint256"
50
+ }
51
+ ],
52
+ "name": "BullaBankerCreated",
53
+ "type": "event"
54
+ },
55
+ {
56
+ "anonymous": false,
57
+ "inputs": [
58
+ {
59
+ "indexed": true,
60
+ "internalType": "address",
61
+ "name": "bullaManager",
62
+ "type": "address"
63
+ },
64
+ {
65
+ "indexed": true,
66
+ "internalType": "uint256",
67
+ "name": "tokenId",
68
+ "type": "uint256"
69
+ },
70
+ {
71
+ "indexed": true,
72
+ "internalType": "address",
73
+ "name": "updatedBy",
74
+ "type": "address"
75
+ },
76
+ {
77
+ "indexed": false,
78
+ "internalType": "bytes32",
79
+ "name": "tag",
80
+ "type": "bytes32"
81
+ },
82
+ {
83
+ "indexed": false,
84
+ "internalType": "uint256",
85
+ "name": "blocktime",
86
+ "type": "uint256"
87
+ }
88
+ ],
89
+ "name": "BullaTagUpdated",
90
+ "type": "event"
91
+ },
92
+ {
93
+ "inputs": [],
94
+ "name": "bullaClaimERC721",
95
+ "outputs": [
96
+ {
97
+ "internalType": "address",
98
+ "name": "",
99
+ "type": "address"
100
+ }
101
+ ],
102
+ "stateMutability": "view",
103
+ "type": "function"
104
+ },
105
+ {
106
+ "inputs": [
107
+ {
108
+ "components": [
109
+ {
110
+ "internalType": "uint256",
111
+ "name": "claimAmount",
112
+ "type": "uint256"
113
+ },
114
+ {
115
+ "internalType": "address",
116
+ "name": "creditor",
117
+ "type": "address"
118
+ },
119
+ {
120
+ "internalType": "address",
121
+ "name": "debtor",
122
+ "type": "address"
123
+ },
124
+ {
125
+ "internalType": "string",
126
+ "name": "description",
127
+ "type": "string"
128
+ },
129
+ {
130
+ "internalType": "uint256",
131
+ "name": "dueBy",
132
+ "type": "uint256"
133
+ },
134
+ {
135
+ "internalType": "address",
136
+ "name": "claimToken",
137
+ "type": "address"
138
+ },
139
+ {
140
+ "components": [
141
+ {
142
+ "internalType": "bytes32",
143
+ "name": "hash",
144
+ "type": "bytes32"
145
+ },
146
+ {
147
+ "internalType": "uint8",
148
+ "name": "hashFunction",
149
+ "type": "uint8"
150
+ },
151
+ {
152
+ "internalType": "uint8",
153
+ "name": "size",
154
+ "type": "uint8"
155
+ }
156
+ ],
157
+ "internalType": "struct Multihash",
158
+ "name": "attachment",
159
+ "type": "tuple"
160
+ }
161
+ ],
162
+ "internalType": "struct BullaBanker.ClaimParams",
163
+ "name": "claim",
164
+ "type": "tuple"
165
+ },
166
+ {
167
+ "internalType": "bytes32",
168
+ "name": "bullaTag",
169
+ "type": "bytes32"
170
+ },
171
+ {
172
+ "internalType": "string",
173
+ "name": "_tokenUri",
174
+ "type": "string"
175
+ }
176
+ ],
177
+ "name": "createBullaClaim",
178
+ "outputs": [
179
+ {
180
+ "internalType": "uint256",
181
+ "name": "",
182
+ "type": "uint256"
183
+ }
184
+ ],
185
+ "stateMutability": "nonpayable",
186
+ "type": "function"
187
+ },
188
+ {
189
+ "inputs": [
190
+ {
191
+ "internalType": "uint256",
192
+ "name": "tokenId",
193
+ "type": "uint256"
194
+ },
195
+ {
196
+ "internalType": "bytes32",
197
+ "name": "newTag",
198
+ "type": "bytes32"
199
+ }
200
+ ],
201
+ "name": "updateBullaTag",
202
+ "outputs": [],
203
+ "stateMutability": "nonpayable",
204
+ "type": "function"
205
+ }
206
+ ]