update the license files to make go do happy

LICENSE

@@ -1,25 +0,0 @@
-The contents of this repository are Copyright (c) corresponding authors and
-contributors, licensed under the `Permissive License Stack` meaning either of:
-
-- Apache-2.0 Software License: https://www.apache.org/licenses/LICENSE-2.0
-  ([...4tr2kfsq](https://dweb.link/ipfs/bafkreiankqxazcae4onkp436wag2lj3ccso4nawxqkkfckd6cg4tr2kfsq))
-
-- MIT Software License: https://opensource.org/licenses/MIT
-  ([...vljevcba](https://dweb.link/ipfs/bafkreiepofszg4gfe2gzuhojmksgemsub2h4uy2gewdnr35kswvljevcba))
-
-You may not use the contents of this repository except in compliance
-with one of the listed Licenses. For an extended clarification of the
-intent behind the choice of Licensing please refer to
-https://protocol.ai/blog/announcing-the-permissive-license-stack/
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the terms listed in this notice is distributed on
-an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
-either express or implied. See each License for the specific language
-governing permissions and limitations under that License.
-
-<!--- SPDX-License-Identifier: Apache-2.0 OR MIT -->
-
-`SPDX-License-Identifier: Apache-2.0 OR MIT`
-
-Verbatim copies of both licenses are included in the LICENSE-APACHE-2.0 and LICENSE-MIT files.

LICENSE-MIT

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 UCAN Working Group - All rights reserved
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

LICENSE.md

@@ -1,6 +1,35 @@
+The contents of this repository are Copyright (c) corresponding authors and
+contributors, licensed under the `Permissive License Stack` meaning either of:
+
+- Apache-2.0 Software License: https://www.apache.org/licenses/LICENSE-2.0
+  ([...4tr2kfsq](https://dweb.link/ipfs/bafkreiankqxazcae4onkp436wag2lj3ccso4nawxqkkfckd6cg4tr2kfsq))
+
+- MIT Software License: https://opensource.org/licenses/MIT
+  ([...vljevcba](https://dweb.link/ipfs/bafkreiepofszg4gfe2gzuhojmksgemsub2h4uy2gewdnr35kswvljevcba))
+
+You may not use the contents of this repository except in compliance
+with one of the listed Licenses. For an extended clarification of the
+intent behind the choice of Licensing please refer to
+https://protocol.ai/blog/announcing-the-permissive-license-stack/
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the terms listed in this notice is distributed on
+an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied. See each License for the specific language
+governing permissions and limitations under that License.
+
+<!--- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+
+`SPDX-License-Identifier: Apache-2.0 OR MIT`
+
+Verbatim copies of both licenses are included below:
+
+<details><summary>Apache-2.0 Software License</summary>
+
+```
                                  Apache License
                            Version 2.0, January 2004
-                        http://www.apache.org/licenses/
+                        https://www.apache.org/licenses/
 
    TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
 
@@ -174,28 +203,30 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
+```
 
-   APPENDIX: How to apply the Apache License to your work.
+</details>
 
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
+<details><summary>MIT Software License</summary>
 
-   Copyright 2025 UCAN Working Group - All right reserved
+```
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
 
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
 
-       http://www.apache.org/licenses/LICENSE-2.0
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+```
 
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
+</details>

README.md

@@ -12,6 +12,43 @@ Include the `go-varsig` library by running the following command:
 go get github.com/ucan-wg/go-varsig@latest
 ```
 
+## Quickstart
+
+```go
+func ExampleDecode() {
+	example, err := base64.RawStdEncoding.DecodeString("NAHtAe0BE3E")
+	handleErr(err)
+
+	vs, err := varsig.Decode(example)
+	handleErr(err)
+
+	fmt.Printf("%T\n", vs)
+	fmt.Printf("Algorithm: %d\n", vs.Algorithm())
+	fmt.Printf("Hash: %d\n", vs.Hash())
+	fmt.Printf("PayloadEncoding: %d\n", vs.PayloadEncoding())
+
+	// Output:
+	// varsig.EdDSAVarsig
+	// Algorithm: 237
+	// Hash: 19
+	// PayloadEncoding: 3
+}
+
+func ExampleEncode() {
+	edDSAVarsig := varsig.NewEdDSAVarsig(
+		varsig.CurveEd25519,
+		varsig.HashSha2_512,
+		varsig.PayloadEncodingDAGCBOR,
+	)
+
+	b64 := base64.RawStdEncoding.EncodeToString(edDSAVarsig.Encode())
+	fmt.Print(b64)
+
+	// Output:
+	// NAHtAe0BE3E
+}
+```
+
 ## Documentation
 
 Documentation for this library is provided as Go docs at

common_test.go

@@ -115,7 +115,7 @@ func TestRoundTrip(t *testing.T) {
 			require.NoError(t, err)
 
 			require.Equal(t, tc.varsig.Version(), rt.Version())
-			require.Equal(t, tc.varsig.Discriminator(), rt.Discriminator())
+			require.Equal(t, tc.varsig.Algorithm(), rt.Algorithm())
 			require.Equal(t, tc.varsig.PayloadEncoding(), rt.PayloadEncoding())
 
 			switch vs := tc.varsig.(type) {

constant.go

@@ -173,14 +173,14 @@ func EncodePayloadEncoding(enc PayloadEncoding) []byte {
 	return res
 }
 
-// Discriminator is (usually) the value representing the public key type of
+// Algorithm is (usually) the value representing the public key type of
 // the algorithm used to create the signature.
 //
 // There is no set list of constants here, nor is there a decode function
 // as the author of an implementation should include the constant with the
 // implementation, and the decoding is handled by the Handler, which uses
-// the Discriminator to choose the correct implementation.  Also note that
-// some of the Discriminator values for a specific implementation have
+// the Algorithm to choose the correct implementation.  Also note that
+// some of the Algorithm values for a specific implementation have
 // changed between varsig v0 and v1, so it's possible to have more than one
 // constant defined per implementation.
-type Discriminator uint64
+type Algorithm uint64

ecdsa.go

@@ -5,8 +5,8 @@ import (
 	"fmt"
 )
 
-// DiscriminatorECDSA is the value specifying an ECDSA signature.
-const DiscriminatorECDSA = Discriminator(0xec)
+// AlgorithmECDSA is the value specifying an ECDSA signature.
+const AlgorithmECDSA = Algorithm(0xec)
 
 // ECDSACurve are values that specify which ECDSA curve is used when
 // generating the signature.
@@ -51,7 +51,7 @@ type ECDSAVarsig struct {
 func NewECDSAVarsig(curve ECDSACurve, hashAlgorithm Hash, payloadEncoding PayloadEncoding) ECDSAVarsig {
 	return ECDSAVarsig{
 		varsig: varsig{
-			disc:   DiscriminatorECDSA,
+			algo:   AlgorithmECDSA,
 			payEnc: payloadEncoding,
 		},
 		curve:   curve,

eddsa.go

@@ -5,8 +5,8 @@ import (
 	"fmt"
 )
 
-// DiscriminatorEdDSA is the value specifying an EdDSA signature.
-const DiscriminatorEdDSA = Discriminator(0xed)
+// AlgorithmEdDSA is the value specifying an EdDSA signature.
+const AlgorithmEdDSA = Algorithm(0xed)
 
 // EdDSACurve are values that specify which Edwards curve is used when
 // generating the signature.
@@ -49,7 +49,7 @@ type EdDSAVarsig struct {
 func NewEdDSAVarsig(curve EdDSACurve, hashAlgorithm Hash, payloadEncoding PayloadEncoding) EdDSAVarsig {
 	return EdDSAVarsig{
 		varsig: varsig{
-			disc:   DiscriminatorEdDSA,
+			algo:   AlgorithmEdDSA,
 			payEnc: payloadEncoding,
 		},
 		curve:   curve,

eddsa_test.go

@@ -29,7 +29,7 @@ func TestUCANExampleV1(t *testing.T) {
 		require.True(t, ok)
 
 		assert.Equal(t, varsig.Version1, ed25519V.Version())
-		assert.Equal(t, varsig.DiscriminatorEdDSA, ed25519V.Discriminator())
+		assert.Equal(t, varsig.AlgorithmEdDSA, ed25519V.Algorithm())
 		assert.Equal(t, varsig.CurveEd25519, ed25519V.Curve())
 		assert.Equal(t, varsig.HashSha2_512, ed25519V.Hash())
 		assert.Equal(t, varsig.PayloadEncodingDAGCBOR, ed25519V.PayloadEncoding())

error.go

@@ -16,9 +16,9 @@ var ErrUnknownHash = errors.New("unknown hash algorithm")
 // for this field may vary based on the varsig version.
 var ErrUnsupportedPayloadEncoding = errors.New("unsupported payload encoding")
 
-// ErrUnknownDiscriminator is returned when the Registry doesn't have a
+// ErrUnknownAlgorithm is returned when the Registry doesn't have a
 // parsing function for the decoded signing algorithm.
-var ErrUnknownDiscriminator = errors.New("unknown signing algorithm")
+var ErrUnknownAlgorithm = errors.New("unknown signing algorithm")
 
 // ErrUnknownEdDSACurve is returned when the decoded uvarint isn't either
 // CurveEd25519 or CurveEd448.

registry.go

@@ -22,15 +22,15 @@ type DecodeFunc func(BytesReader) (Varsig, error)
 
 // Registry contains a mapping between known signing algorithms and
 // functions that can parse varsigs for that signing algorithm.
-type Registry map[Discriminator]DecodeFunc
+type Registry map[Algorithm]DecodeFunc
 
 // DefaultRegistry provides a Registry containing the mappings for the
 // signing algorithms which have an implementation within this library.
 func DefaultRegistry() Registry {
-	return map[Discriminator]DecodeFunc{
-		DiscriminatorRSA:   decodeRSA,
-		DiscriminatorEdDSA: decodeEdDSA,
-		DiscriminatorECDSA: decodeECDSA,
+	return map[Algorithm]DecodeFunc{
+		AlgorithmRSA:   decodeRSA,
+		AlgorithmEdDSA: decodeEdDSA,
+		AlgorithmECDSA: decodeECDSA,
 	}
 }
 
@@ -41,7 +41,7 @@ func NewRegistry() Registry {
 
 // Register allows new mappings between a signing algorithm and its parsing
 // function to the Registry.
-func (rs Registry) Register(alg Discriminator, decodeFunc DecodeFunc) {
+func (rs Registry) Register(alg Algorithm, decodeFunc DecodeFunc) {
 	rs[alg] = decodeFunc
 }
 
@@ -63,7 +63,7 @@ func (rs Registry) DecodeStream(r BytesReader) (Varsig, error) {
 		return nil, fmt.Errorf("%w: expected %d, got %d", ErrBadPrefix, Prefix, pre)
 	}
 
-	vers, disc, err := rs.decodeVersAnddisc(r)
+	vers, algo, err := rs.decodeVersAndAlgo(r)
 	if err != nil {
 		return nil, err
 	}
@@ -72,15 +72,15 @@ func (rs Registry) DecodeStream(r BytesReader) (Varsig, error) {
 		return nil, fmt.Errorf("%w: %d", ErrUnsupportedVersion, vers)
 	}
 
-	decodeFunc, ok := rs[Discriminator(disc)]
+	decodeFunc, ok := rs[Algorithm(algo)]
 	if !ok {
-		return nil, fmt.Errorf("%w: %x", ErrUnknownDiscriminator, disc)
+		return nil, fmt.Errorf("%w: %x", ErrUnknownAlgorithm, algo)
 	}
 
 	return decodeFunc(r)
 }
 
-func (rs Registry) decodeVersAnddisc(r BytesReader) (Version, Discriminator, error) {
+func (rs Registry) decodeVersAndAlgo(r BytesReader) (Version, Algorithm, error) {
 	vers, err := binary.ReadUvarint(r)
 	if err != nil {
 		return Version(vers), 0, err
@@ -91,10 +91,10 @@ func (rs Registry) decodeVersAnddisc(r BytesReader) (Version, Discriminator, err
 	}
 
 	if vers >= 64 {
-		return 0, Discriminator(vers), nil
+		return 0, Algorithm(vers), nil
 	}
 
-	disc, err := binary.ReadUvarint(r)
+	algo, err := binary.ReadUvarint(r)
 
-	return Version(vers), Discriminator(disc), err
+	return Version(vers), Algorithm(algo), err
 }

registry_test.go

@@ -21,35 +21,35 @@ func TestRegistry_Decode(t *testing.T) {
 		vs, err := reg.DecodeStream(bytes.NewReader(data))
 		require.NoError(t, err)
 		assert.Equal(t, varsig.Version1, vs.Version())
-		assert.Equal(t, testDiscriminator1, vs.Discriminator())
+		assert.Equal(t, testAlgorithm1, vs.Algorithm())
 	})
 }
 
 const (
-	testDiscriminator0 varsig.Discriminator = 0x1000
-	testDiscriminator1 varsig.Discriminator = 0x1001
+	testAlgorithm0 varsig.Algorithm = 0x1000
+	testAlgorithm1 varsig.Algorithm = 0x1001
 )
 
 func testRegistry(t *testing.T) varsig.Registry {
 	t.Helper()
 
 	reg := varsig.NewRegistry()
-	reg.Register(testDiscriminator0, testDecodeFunc(testDiscriminator0))
-	reg.Register(testDiscriminator1, testDecodeFunc(testDiscriminator1))
+	reg.Register(testAlgorithm0, testDecodeFunc(testAlgorithm0))
+	reg.Register(testAlgorithm1, testDecodeFunc(testAlgorithm1))
 
 	return reg
 }
 
-func testDecodeFunc(disc varsig.Discriminator) varsig.DecodeFunc {
+func testDecodeFunc(algo varsig.Algorithm) varsig.DecodeFunc {
 	return func(r varsig.BytesReader) (varsig.Varsig, error) {
-		return &testVarsig{disc: disc}, nil
+		return &testVarsig{algo: algo}, nil
 	}
 }
 
 var _ varsig.Varsig = testVarsig{}
 
 type testVarsig struct {
-	disc   varsig.Discriminator
+	algo   varsig.Algorithm
 	payEnc varsig.PayloadEncoding
 }
 
@@ -57,8 +57,8 @@ func (v testVarsig) Version() varsig.Version {
 	return varsig.Version1
 }
 
-func (v testVarsig) Discriminator() varsig.Discriminator {
-	return v.disc
+func (v testVarsig) Algorithm() varsig.Algorithm {
+	return v.algo
 }
 
 func (v testVarsig) Hash() varsig.Hash {

rsa.go

@@ -4,8 +4,8 @@ import (
 	"encoding/binary"
 )
 
-// DiscriminatorRSA is the value specifying an RSA signature.
-const DiscriminatorRSA = Discriminator(0x1205)
+// AlgorithmRSA is the value specifying an RSA signature.
+const AlgorithmRSA = Algorithm(0x1205)
 
 var _ Varsig = RSAVarsig{}
 
@@ -22,7 +22,7 @@ type RSAVarsig struct {
 func NewRSAVarsig(hashAlgorithm Hash, keyLen uint64, payloadEncoding PayloadEncoding) RSAVarsig {
 	return RSAVarsig{
 		varsig: varsig{
-			disc:   DiscriminatorRSA,
+			algo:   AlgorithmRSA,
 			payEnc: payloadEncoding,
 		},
 		hashAlg: hashAlgorithm,

rsa_test.go

@@ -29,7 +29,7 @@ func TestRSAVarsig(t *testing.T) {
 		require.True(t, ok)
 
 		require.Equal(t, varsig.Version1, rsaVs.Version())
-		require.Equal(t, varsig.DiscriminatorRSA, rsaVs.Discriminator())
+		require.Equal(t, varsig.AlgorithmRSA, rsaVs.Algorithm())
 		require.Equal(t, varsig.HashSha2_256, rsaVs.Hash())
 		require.Equal(t, varsig.PayloadEncodingDAGCBOR, rsaVs.PayloadEncoding())
 		require.Equal(t, uint64(keyLen), rsaVs.KeyLength())

varsig.go

@@ -29,8 +29,8 @@ type Varsig interface {
 	// Version returns the varsig's version field.
 	Version() Version
 
-	// Discriminator returns the algorithm used to produce the corresponding signature.
-	Discriminator() Discriminator
+	// Algorithm returns the algorithm used to produce the corresponding signature.
+	Algorithm() Algorithm
 
 	// Hash returns the hash used on the data before signature.
 	Hash() Hash
@@ -55,7 +55,7 @@ func DecodeStream(r BytesReader) (Varsig, error) {
 }
 
 type varsig struct {
-	disc   Discriminator
+	algo   Algorithm
 	payEnc PayloadEncoding
 }
 
@@ -64,10 +64,10 @@ func (v varsig) Version() Version {
 	return Version1
 }
 
-// Discriminator returns the algorithm used to produce the corresponding
+// Algorithm returns the algorithm used to produce the corresponding
 // signature.
-func (v varsig) Discriminator() Discriminator {
-	return v.disc
+func (v varsig) Algorithm() Algorithm {
+	return v.algo
 }
 
 // PayloadEncoding returns the codec that was used to encode the signed
@@ -84,7 +84,7 @@ func (v varsig) encode() []byte {
 
 	buf = binary.AppendUvarint(buf, Prefix)
 	buf = binary.AppendUvarint(buf, uint64(Version1))
-	buf = binary.AppendUvarint(buf, uint64(v.disc))
+	buf = binary.AppendUvarint(buf, uint64(v.algo))
 
 	return buf
 }

varsig_test.go

@@ -1,7 +1,9 @@
 package varsig_test
 
 import (
+	"encoding/base64"
 	"encoding/hex"
+	"fmt"
 	"io"
 	"testing"
 
@@ -11,6 +13,39 @@ import (
 	"github.com/ucan-wg/go-varsig"
 )
 
+func ExampleDecode() {
+	example, err := base64.RawStdEncoding.DecodeString("NAHtAe0BE3E")
+	handleErr(err)
+
+	vs, err := varsig.Decode(example)
+	handleErr(err)
+
+	fmt.Printf("%T\n", vs)
+	fmt.Printf("Algorithm: %d\n", vs.Algorithm())
+	fmt.Printf("Hash: %d\n", vs.Hash())
+	fmt.Printf("PayloadEncoding: %d\n", vs.PayloadEncoding())
+
+	// Output:
+	// varsig.EdDSAVarsig
+	// Algorithm: 237
+	// Hash: 19
+	// PayloadEncoding: 3
+}
+
+func ExampleEncode() {
+	edDSAVarsig := varsig.NewEdDSAVarsig(
+		varsig.CurveEd25519,
+		varsig.HashSha2_512,
+		varsig.PayloadEncodingDAGCBOR,
+	)
+
+	b64 := base64.RawStdEncoding.EncodeToString(edDSAVarsig.Encode())
+	fmt.Print(b64)
+
+	// Output:
+	// NAHtAe0BE3E
+}
+
 func TestDecode(t *testing.T) {
 	t.Parallel()
 
@@ -65,7 +100,7 @@ func TestDecode(t *testing.T) {
 		require.NoError(t, err)
 
 		vs, err := varsig.Decode(data)
-		require.ErrorIs(t, err, varsig.ErrUnknownDiscriminator)
+		require.ErrorIs(t, err, varsig.ErrUnknownAlgorithm)
 		assert.Nil(t, vs)
 	})
 
@@ -112,3 +147,9 @@ func TestDecode(t *testing.T) {
 		assert.Nil(t, vs)
 	})
 }
+
+func handleErr(err error) {
+	if err != nil {
+		panic(err)
+	}
+}