Overgive Chain

Overgive Chain is a Cosmos SDK blockchain built with Ignite CLI.

Overgive Chain is designed as a supporting blockchain layer for the Overgive Crowdfunding Platform (Web2 application). It is used to store immutable records of donation data and donation distribution (delivery) data as a cryptographic proof layer to ensure transparency, integrity, and auditability. Full business logic and detailed data remain in the Web2 backend, while the blockchain functions as a tamper-proof public ledger.

GitHub Repository (Web App):
https://github.com/zakoraa/overgive-web

1 SETUP & EXECUTION STEPS

Step 1: Prerequisites (Install First)

Install Go 1.24.x recommended (must match go.mod)

https://go.dev/dl/

Verify:

go version

Install Ignite CLI

curl https://get.ignite.com/cli! | bash

Verify:

ignite version

Step 2: Run Blockchain (Development Mode)

Inside project directory:

ignite chain serve

Build the chain
Initialize state
Start validator
Expose RPC at: http://localhost:26657

Step 3: Initialize Wallet

Check available keys:

overgive-chaind keys list

Check admin address:

overgive-chaind keys show overgive-admin -a

Create new wallet:

overgive-chaind keys add writer1

Check address:

overgive-chaind keys show writer1 -a

Step 4: Fund Wallet

Send token from admin to writer1:

overgive-chaind tx bank send   overgive-admin   $(overgive-chaind keys show writer1 -a)   1000000stake   --chain-id overgivechain   --gas auto -y

Verify balance:

overgive-chaind query bank balances $(overgive-chaind keys show writer1 -a)

If balance appears -> account is active and ready to send transactions.

Step 5: Create Allowed Address (IMPORTANT FLOW)

Before recording Donation or Delivery,
you MUST register the address in permissions.

Only admin/authority can do this.

overgive-chaind tx permissions create-allowed   <address>   --from overgive-admin   --chain-id overgivechain   --gas auto -y

Example:

overgive-chaind tx permissions create-allowed   $(overgive-chaind keys show writer1 -a)   --from overgive-admin   --chain-id overgivechain   --gas auto -y

Verify:

overgive-chaind query permissions get-allowed <address>

If not allowed -> Donation & Delivery will fail with:
"not allowed writer"

For full Permissions module documentation, see:
SECTION: 2.1 PERMISSIONS MODULE

Step 6: Record Donation

Only allowed address can execute.

overgive-chaind tx donation record-donation   campaign1   750000   IDR   PAY123   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb   --from writer1   --chain-id overgivechain   --gas auto -y

Query Donation:

overgive-chaind query donation donations

For full Donation module documentation, see:
SECTION: 2.2 DONATION MODULE

Step 7: Record Delivery

Only allowed address can execute.

overgive-chaind tx delivery record-delivery   campaign1   "Laporan Bantuan Palestina"   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb   --from writer1   --chain-id overgivechain   --gas auto -y

Query Delivery:

overgive-chaind query delivery deliveries

For full Delivery module documentation, see:
SECTION: 2.3 DELIVERY MODULE

Full Execution Flow (Short Version)

Install Go & Ignite
Run ignite chain serve
Create wallet (writer1)
Fund wallet (bank send from admin)
Admin -> create-allowed address
Allowed wallet -> record donation
Allowed wallet -> record delivery
Query data

Without create-allowed → transactions will fail.

Useful Commands

Check address:

overgive-chaind keys show <name> -a

Check tx by hash:

overgive-chaind query tx <txhash>

2 MODULE DOCUMENTATION

2.1 PERMISSIONS MODULE

The Permissions module controls which addresses are allowed to record Donation and Delivery data on-chain.

If an address is not registered, transactions will fail with:
"not allowed writer"

Message Execution (Msg):

1. Create Allowed Address

Registers a new address as an authorized writer. Only admin/authority can execute this transaction.

overgive-chaind tx permissions create-allowed <address> --from overgive-admin --chain-id overgivechain --gas auto -y

2. Delete Allowed Address

Removes an address from the allowed list. After deletion, the address can no longer record data.

overgive-chaind tx permissions delete-allowed <address> --from overgive-admin --chain-id overgivechain --gas auto -y

Query Permissions:

1. Query Allowed Address

Checks whether an address is registered.

overgive-chaind query permissions get-allowed <address>

2. List All Allowed Addresses

Returns all registered allowed addresses (supports pagination).

overgive-chaind query permissions list-allowed

3. Query Module Parameters

Returns current permissions module parameters.

overgive-chaind query permissions params

PERMISSIONS MODULE – Endpoints

Base REST Path:

/overgive-chain/permissions/v1

1. Query Module Parameters

GET /overgive-chain/permissions/v1/params

http://localhost:1317/overgive-chain/permissions/v1/params

2. Query Allowed Address

GET /overgive-chain/permissions/v1/allowed/{address}

http://localhost:1317/overgive-chain/permissions/v1/allowed/overgive1xxxxx

3. List All Allowed Addresses

GET /overgive-chain/permissions/v1/allowed

With pagination:

GET /overgive-chain/permissions/v1/allowed?pagination.limit=10

2.2 DONATION MODULE

The Donation module stores immutable donation records as cryptographic proof. Only allowed addresses can record donations.

Message Execution (Msg):

1. Record Donation

Creates a new donation record on-chain.

overgive-chaind tx donation record-donation   campaign1   750000   IDR   PAY123   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb   --from writer1   --chain-id overgivechain   --gas auto -y

Query Donation:

1. List All Donations

Returns all donation records stored on-chain (with pagination).

overgive-chaind query donation donations

Example output:

donations:
- id: "0"
  amount: "750000"
  campaign_id: campaign1
  creator: overgive1z52eaynmwfj7qeu7dw7xyyat3grj3hajlu2l9k
  currency: IDR
  donation_hash: 36c3e2478cd6c07c98c1ad8cc0644e75b882f30eefcb0b6e0a29fee4d8ab3f0c
  metadata_hash: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  payment_reference_id: PAY123
  recorded_at: "1772425897"
pagination:
  total: "1"

If the dataset grows, use pagination:

overgive-chaind query donation donations --page-limit 10

2. Query Donation by ID

Retrieves a single donation using its internal auto-increment ID.

overgive-chaind query donation donation --id <id>

Example:

overgive-chaind query donation donation --id 0

3. Query Donation by Hash (Recommended for Web2 Integration)

Retrieves a donation using its unique donation_hash.

overgive-chaind query donation donation-by-hash   --donation-hash <donation_hash>

DONATION MODULE – Endpoints

Base REST Path:

/overgivechain/donation/v1

1. Query Module Parameters

GET /overgivechain/donation/v1/params

http://localhost:1317/overgivechain/donation/v1/params

2. List All Donations

GET /overgivechain/donation/v1/donations

With pagination:

GET /overgivechain/donation/v1/donations?pagination.limit=10

3. Query Donation by ID

GET /overgivechain/donation/v1/donations/{id}

http://localhost:1317/overgivechain/donation/v1/donations/0

4. Query Donation by Hash

GET /overgivechain/donation/v1/donations/hash/{donation_hash}

http://localhost:1317/overgivechain/donation/v1/donations/hash/36c3e2478cd6c07c98c1ad8cc0644e75b882f30eefcb0b6e0a29fee4d8ab3f0c

2.3 DELIVERY MODULE

The Delivery module stores immutable distribution (delivery) records linked to campaign activities.

Only allowed addresses can record delivery data.

Message Execution (Msg):

1. Record Delivery

Creates a new delivery record on-chain.

overgive-chaind tx delivery record-delivery   campaign1   "Laporan Bantuan Palestina"   aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa   bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb   --from writer1   --chain-id overgivechain   --gas auto -y

Query Delivery:

1. List All Deliveries

Returns all delivery records stored on-chain (with pagination).

overgive-chaind query delivery deliveries

Example output:


deliveries:
- campaign_id: campaign1
  creator: overgive1yz7hxhedy7a45kq55z3kxcr7ta99zt0eda5hf9
  delivery_hash: bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
  note_hash: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
  recorded_at: "1772126435"
  title: Laporan Bantuan Palestina
pagination:
  total: "1"

If the dataset grows, use pagination:

overgive-chaind query delivery deliveries --page-limit 10

2. Query Delivery by ID

Retrieves a single delivery using its internal auto-increment ID.

overgive-chaind query delivery delivery --id <id>

Example:

overgive-chaind query delivery delivery --id 0

3. Query Delivery by Hash (Recommended for Web2 Integration)

Retrieves a delivery using its unique delivery_hash.

overgive-chaind query delivery delivery-by-hash   --delivery-hash <delivery_hash>

DELIVERY MODULE – Endpoints

Base REST Path:

/overgivechain/delivery/v1

1. Query Module Parameters

GET /overgivechain/delivery/v1/params

2. List All Deliveries

GET /overgivechain/delivery/v1/deliveries

With pagination:

GET /overgivechain/delivery/v1/deliveries?pagination.limit=10

3. Query Delivery by ID

GET /overgivechain/delivery/v1/deliveries/{id}

4. Query Delivery by Hash

GET /overgivechain/delivery/v1/deliveries/hash/{delivery_hash}

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github/workflows		.github/workflows
app		app
cmd/overgive-chaind		cmd/overgive-chaind
docs		docs
proto		proto
testutil/sample		testutil/sample
x		x
.gitignore		.gitignore
Makefile		Makefile
buf.lock		buf.lock
buf.yaml		buf.yaml
config.yml		config.yml
go.mod		go.mod
go.sum		go.sum
readme.md		readme.md

Folders and files

Latest commit

History

Repository files navigation

Overgive Chain

TABLE OF CONTENTS

1 SETUP & EXECUTION STEPS

Step 1: Prerequisites (Install First)

Install Go 1.24.x recommended (must match go.mod)

Install Ignite CLI

Step 2: Run Blockchain (Development Mode)

Step 3: Initialize Wallet

Step 4: Fund Wallet

Step 5: Create Allowed Address (IMPORTANT FLOW)

Step 6: Record Donation

Step 7: Record Delivery

Full Execution Flow (Short Version)

Useful Commands

2 MODULE DOCUMENTATION

2.1 PERMISSIONS MODULE

Message Execution (Msg):

1. Create Allowed Address

2. Delete Allowed Address

Query Permissions:

1. Query Allowed Address

2. List All Allowed Addresses

3. Query Module Parameters

PERMISSIONS MODULE – Endpoints

1. Query Module Parameters

2. Query Allowed Address

3. List All Allowed Addresses

2.2 DONATION MODULE

Message Execution (Msg):

1. Record Donation

Query Donation:

1. List All Donations

2. Query Donation by ID

3. Query Donation by Hash (Recommended for Web2 Integration)

DONATION MODULE – Endpoints

1. Query Module Parameters

2. List All Donations

3. Query Donation by ID

4. Query Donation by Hash

2.3 DELIVERY MODULE

Message Execution (Msg):

1. Record Delivery

Query Delivery:

1. List All Deliveries

2. Query Delivery by ID

3. Query Delivery by Hash (Recommended for Web2 Integration)

DELIVERY MODULE – Endpoints

1. Query Module Parameters

2. List All Deliveries

3. Query Delivery by ID

4. Query Delivery by Hash

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages