Add AI Credits management dashboard with source-filtered historical credits

.agents/skills/gooddollar/CONTRIBUTING.md

@@ -0,0 +1,121 @@
+# Contributing to GoodSkills
+
+This repository is an AI skill pack. The goal of each update is to make agent behavior more reliable, more explicit, and easier to audit.
+
+## Update workflow
+
+1. Define the user-facing problem first.
+2. For contract-related updates, add or update Rich ABI first (`references/contracts/*.abi.yaml`), then refresh selectors.
+3. Decide the remaining artifact types:
+   - `references/guides/` for "what to do"
+   - `references/deep-researches/` for "why it works this way"
+   - `scripts/` for deterministic and repeatable execution
+4. Update `SKILL.md` routing so the new artifact is discoverable.
+5. Validate consistency (paths, naming, links, selectors, assumptions).
+
+If a change touches contract behavior, treat Rich ABI update/add as mandatory first step before guides, deep-research, or scripts.
+
+## Add or update a guide
+
+Use guides for execution playbooks and operator workflows.
+
+Required structure:
+
+- title and one-line usage trigger
+- `## Goal`
+- `## Required inputs`
+- `## Execution flow` as numbered steps
+- deterministic snippet when execution is non-trivial
+- failure handling and output contract
+
+Guide rules:
+
+- prefer explicit pre-checks before state-changing actions
+- include only one primary workflow per file
+- use [GoodProtocol `releases/deployment.json`](https://github.com/GoodDollar/GoodProtocol/blob/master/releases/deployment.json) as the **only** source for contract addresses (rich ABI `meta.deployments` mirrors those rows); use GoodDocs for behavior and UX, not for resolving addresses; use on-chain `NameService.getAddress` only when the deployment documents the string key
+- avoid implementation-deep theory; keep that in deep-research files
+
+After adding a guide:
+
+- add it to `SKILL.md` in `Guides`
+- add an entry in `Use-case to guide map`
+
+## Add or update a deep-research note
+
+Use deep-research files for architecture, rationale, tradeoffs, and root-cause logic.
+
+Deep-research rules:
+
+- explain causality, not only API surfaces
+- distinguish current behavior from legacy behavior
+- link source contracts/docs for traceability
+- keep language natural and decision-oriented
+
+Do not turn deep-research files into step-by-step runbooks; move operational steps into guides.
+
+## Add or update Rich ABI YAML
+
+Location: `references/contracts/`.
+
+For each contract:
+
+- create or update `Foo.abi.yaml`
+- generate or refresh `Foo.selectors.yaml`
+- include function-level notes for non-obvious behavior
+- when `meta.deployments` lists concrete addresses, add **`creationBlock`** next to each **`address`** (placement: `references/contracts/_rich-abi-yaml-format.md`; using it as **`fromBlock`** for log or HyperSync fetches: `references/guides/hypersync-hyperrpc.md`)
+
+Minimum ABI documentation quality:
+
+- correct mutability, inputs, outputs
+- access pattern (`owner`, `avatar`, `anyone`, etc.) where relevant
+- emitted events and practical errors
+- notes for routing/edge-case semantics
+
+Source-of-truth policy:
+
+- prefer canonical contract repos (GoodProtocol, GoodBridge, mento-core)
+- avoid inferred behavior when source is unclear
+- update notes when protocol behavior changed
+
+Selector generation:
+
+```bash
+node scripts/selectors.mjs generate Foo.abi.yaml
+```
+
+## Add or update scripts
+
+Location: `scripts/`.
+
+Use scripts when:
+
+- a workflow is repeated
+- deterministic output is needed
+- manual querying is error-prone
+
+Script standards:
+
+- require inputs through env vars or explicit args
+- fail loudly with actionable messages
+- print structured output for easy reuse
+- keep script intent narrow
+
+When a script supports a guide:
+
+- reference it from that guide
+- document expected inputs and outputs in the guide
+
+## Naming and organization
+
+- use lowercase kebab-case for guides and deep-research files
+- keep one topic per file
+- avoid duplicate guidance across files
+- prefer updating existing files over creating near-duplicates
+
+## Update checklist before merge
+
+- `SKILL.md` routing updated
+- links resolve and point to public sources
+- guides and deep-research files respect "what" vs "why" separation
+- ABI + selectors pairs are in sync
+- new behavior is reflected in notes where needed

.agents/skills/gooddollar/references/contracts/BuyGDCloneFactory.abi.yaml

@@ -0,0 +1,205 @@
+meta:
+  name: BuyGDCloneFactory
+  version: "1"
+  source:
+    - https://raw.githubusercontent.com/GoodDollar/GoodProtocol/master/contracts/utils/BuyGDClone.sol
+  note: >
+    Deterministic clone factory for BuyGDCloneV2 and DonateGDClone. Used to create per-owner
+    executors and optional create+swap flows for ramp services.
+  deployments:
+    mainnet:
+      production-celo:
+        BuyGDFactoryV2:
+          networkId: 42220
+          address: "0x1F60C4C7037C6766924A43666B781ED1479587a2"
+          creationBlock: 22909812
+        BuyGDFactory:
+          networkId: 42220
+          address: "0x00e533B7d6255D05b7f15034B1c989c21F51b91C"
+          creationBlock: 21006324
+  related:
+    - references/deep-researches/on-off-ramp-service.md
+    - references/guides/on-off-ramp.md
+
+create:
+  notes:
+    - "Deploys deterministic BuyGDCloneV2 clone for owner and initializes it."
+    - "Difference vs createAndSwap: this only deploys; no swap is executed."
+  mutability: nonpayable
+  access: anyone
+  inputs:
+    - owner: address
+  outputs:
+    - clone: address
+
+createDonation:
+  notes:
+    - "Deploys deterministic DonateGDClone with donation target and call payload."
+    - "Difference vs create: deploys donation-capable implementation instead of plain swap clone."
+  mutability: nonpayable
+  access: anyone
+  inputs:
+    - owner: address
+    - donateOrExecTo: address
+    - callData: bytes
+  outputs:
+    - clone: address
+
+createAndSwap:
+  notes:
+    - "One-transaction helper: create BuyGDCloneV2 then immediately call clone.swap(minAmount, msg.sender)."
+    - "Difference vs create: bundles deployment and first swap for faster ramp UX."
+  mutability: nonpayable
+  access: anyone
+  inputs:
+    - owner: address
+    - minAmount: uint256
+  outputs:
+    - clone: address
+
+createDonationAndSwap:
+  notes:
+    - "One-transaction helper for DonateGDClone: deploy, then execute donation flow with optional pre-swap."
+    - "Difference vs createDonation: can execute immediate swap and/or target call instead of deployment only."
+  mutability: nonpayable
+  access: anyone
+  inputs:
+    - owner: address
+    - donateOrExecTo: address
+    - withSwap: bool
+    - minAmount: uint256
+    - callData: bytes
+  outputs:
+    - clone: address
+
+predict:
+  notes:
+    - "Computes deterministic address for create(owner) salt."
+  mutability: view
+  inputs:
+    - owner: address
+  outputs:
+    - clone: address
+
+predictDonation:
+  notes:
+    - "Computes deterministic address for createDonation(owner, donateOrExecTo, callData) salt."
+  mutability: view
+  inputs:
+    - owner: address
+    - donateOrExecTo: address
+    - callData: bytes
+  outputs:
+    - clone: address
+
+getBaseFee:
+  mutability: view
+  inputs: []
+  outputs:
+    - baseFee: uint256
+
+quoter:
+  mutability: pure
+  inputs: []
+  outputs:
+    - addr: address
+
+CUSD:
+  mutability: pure
+  inputs: []
+  outputs:
+    - token: address
+
+celo:
+  mutability: pure
+  inputs: []
+  outputs:
+    - token: address
+
+USDC:
+  mutability: pure
+  inputs: []
+  outputs:
+    - token: address
+
+GLOUSD:
+  mutability: pure
+  inputs: []
+  outputs:
+    - token: address
+
+PERIOD:
+  mutability: pure
+  inputs: []
+  outputs:
+    - seconds: uint24
+
+impl:
+  mutability: view
+  inputs: []
+  outputs:
+    - addr: address
+
+donateImpl:
+  mutability: view
+  inputs: []
+  outputs:
+    - addr: address
+
+gd:
+  mutability: view
+  inputs: []
+  outputs:
+    - token: address
+
+stable:
+  mutability: view
+  inputs: []
+  outputs:
+    - token: address
+
+oracle:
+  mutability: view
+  inputs: []
+  outputs:
+    - addr: address
+
+router:
+  mutability: view
+  inputs: []
+  outputs:
+    - addr: address
+
+mentoBroker:
+  mutability: view
+  inputs: []
+  outputs:
+    - addr: address
+
+mentoExchangeProvider:
+  mutability: view
+  inputs: []
+  outputs:
+    - addr: address
+
+mentoExchangeId:
+  mutability: view
+  inputs: []
+  outputs:
+    - id: bytes32
+
+events:
+  GDSwapToCusd:
+    indexed: []
+    data:
+      - from: address
+      - to: address
+      - amountIn: uint256
+      - amountOut: uint256
+      - note: bytes
+
+errors:
+  NOT_GD_TOKEN: "onTokenTransfer caller is not G$ token."
+  INVALID_TWAP: "TWAP validation failed."
+  RECIPIENT_ZERO: "Recipient cannot be zero address."
+  ZERO_MINAMOUNT: "Minimum amount cannot be zero."

.agents/skills/gooddollar/references/contracts/BuyGDCloneFactory.selectors.yaml

@@ -0,0 +1,27 @@
+# Generated by scripts/selectors.mjs
+functions:
+  create(address): 0x9ed93318
+  createDonation(address,address,bytes): 0x48199e6b
+  createAndSwap(address,uint256): 0x89643a29
+  createDonationAndSwap(address,address,bool,uint256,bytes): 0xeb5621b8
+  predict(address): 0x901b96e7
+  predictDonation(address,address,bytes): 0x3895de30
+  getBaseFee(): 0x15e812ad
+  quoter(): 0xc6bbd5a7
+  CUSD(): 0x758316c9
+  celo(): 0x051ed8ef
+  USDC(): 0x89a30271
+  GLOUSD(): 0x4b5b02d6
+  PERIOD(): 0xb4d1d795
+  impl(): 0x8abf6077
+  donateImpl(): 0x21fc2eef
+  gd(): 0xa5e598fc
+  stable(): 0x22be3de1
+  oracle(): 0x7dc0d1d0
+  router(): 0xf887ea40
+  mentoBroker(): 0x7b89f117
+  mentoExchangeProvider(): 0x4f62feec
+  mentoExchangeId(): 0xd373b333
+events:
+  GDSwapToCusd(address,address,uint256,uint256,bytes): 0x252bc23e3fb01f9986fa157af621236fb8a706ea12622da296e7f2f30d4f1a56
+errors: {}